skpkg: fully migrate documentation files #61
Conversation
| Submodules | ||
| ---------- | ||
|
|
||
| |module| | ||
| -------- | ||
| pyobjcryst.atom module |
There was a problem hiding this comment.
For some reason, I am not able to render these modules locally. Here is how it looks when I run make html:
I'm fairly certain that I've followed how other repos formatted this file as well...
| @@ -50,7 +50,6 @@ | |||
| "sphinx.ext.intersphinx", | |||
| "sphinx_rtd_theme", | |||
| "sphinx_copybutton", | |||
| "m2r", | |||
There was a problem hiding this comment.
I deleted m2r as a dependency because I am unable to run make html to build the documentation. Here is the error message:
sphinx.errors.ExtensionError: Could not import extension m2r (exception: cannot import name 'ErrorString' from 'docutils.core' (/Users/zhimingxu/miniconda3/envs/pyobjcryst-env/lib/python3.13/site-packages/docutils/core.py))
According to the error message, the use of ErrorString seems to have been removed from docutils, while m2r is still importing from it. I realize that this isn't an issue in other repos, but I wasn't sure how to address this error. I did a global search for .md files in this repo and found none, so it should be fine?
| @@ -58,7 +58,7 @@ exclude = [] # exclude packages matching these glob patterns (empty by default) | |||
| namespaces = false # to disable scanning PEP 420 namespaces (true by default) | |||
|
|
|||
| [project.scripts] | |||
| pyobjcryst = "pyobjcryst.app:main" | |||
There was a problem hiding this comment.
pyobjcryst.app doesn't exist. So I modified the project scripts with the best replacement I could find.
| @@ -2,4 +2,3 @@ sphinx | |||
| sphinx_rtd_theme | |||
| sphinx-copybutton | |||
| doctr | |||
| m2r | |||
There was a problem hiding this comment.
other projects have migrated to m2r2, I am not sure if that is a drop-in replacement for m2r. Honestly I am not sure what docutils is doing and how we are using it. I didn't pay close attention to that work that was led I think by @bobleesj and @Sparks29032. Please could you ask around a bit for how to get this going?
Also, quick question, did you find legacy (i.e., already existing) docs for pyobjcryst. It could help me if you could paste a link and I could take a quick look at it.
There was a problem hiding this comment.
I've looked into using m2r2 as a replacement for m2r to build my docs locally, and it seems like I'm getting the same error because it's also attempting to import ErrorString from docutils. According to the docutils documentation , ErrorString is just a error reporting module that was deprecated for docutils >= 0.21 alongside the end of support for python 2. Since we're not using any markdown files in our documentation and m2r is only included to support md parsing in Sphinx (doing a global search tells me that it was only referenced in conf.py, while docutils is not referenced at all), I believe it can be safely removed from our dependencies without affecting our documentation build.
|
@sbillinge this is ready for review. |
|
I am a little nervous about this approach of simply deleting all the scaffolding that skpkgs puts in (getting started secitions, etc.). It would be better to actually quickly write these sections and scaffolding makes it easier. You will need help from Caden for this. He is doing this work for diffpy.cmi. These sections can be very short, just one or two sentences pointing to examples and so on, but by keeping that structure we can expand out the docs in the futrure more easiliy. |
|
@sbillinge ready for review |
No description provided.