Add API reference generated by Sphinx #212
Conversation
This is `sphinx-quickstart` as modified to automatically produce documentation for the module, taking a few hints from fonttools/ufoLib2 to inform structure, build workflow, and styling.
Having an explicit __all__ is necessary to avoid re-exporting objects that we ourselves have imported (e.g. from the standard library). This also helps avoid objects that this project did not author from appearing in the automatically generated Sphinx documentation. This list was generated by: ```python import uharfbuzz print(dir(uharfbuzz)) ``` ...before being manually pruned.
|
Thanks for the speedy review Khaled 💪 I'll see what it would take to run the |
This is following the guidance at:
https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
...in preparation for adding Read the Docs build support, where having
an explicit requirements.txt file to point to will also be helpful.
This is based on the Sphinx reference config file here:
https://docs.readthedocs.io/en/stable/config-file/v2.html#python-install
...with some trimming, customisation for the project, and additional
adjustments recommended for reproducible builds.
|
I've added a template Would someone with maintainer access be willing to follow the Read the Docs procedure required to create a sub-domain and have it insert actions into this repository to populate the docs? Side note: if the pull request option is available for community plans then we may be able to avoid the duplicate runner effort of including a CI job for docs on GitHub too 🚀 |
|
I’m merging this now to see how building on read the docs goes, and we can do any amendments/fixes in another PR. |
I enabled it, I don’t know if it works or not. |
|
I did a few small tweaks and it seems the docs now build https://uharfbuzz.readthedocs.io/en/latest/, time to actually start documenting the code 😄 |
Hello - I've had a stab at #206!
This is largely a modification of
sphinx-quickstartto automatically generate an API reference for the module, taking a few hints from fonttools/ufoLib2 to inform structure, build workflow, and styling.It can be tested as follows:
...and seems to be fairly happy with Cython, aside from a known upstream issue with displaying the types of properties (sphinx-doc/sphinx#7448).
In general, the generated documentation will remain sparse until more docstrings are added, however, it will hopefully still deliver an improvement over reading the sources, especially with the built-in search functionality that Sphinx provides :)
Known caveats:
setup.py; are these the most accurate to use?Note: this is a personal contribution independent of my employer, and so I've submitted from a fork under my personal profile and email to make this distinction ✔️