Suggestions for Improvements of API Documentation
Closed this issue · 3 comments
Hi, ponnhide
Currently, the API documentation is in the README, and its content is roughly the same as the docstring (by @DanNBullock work #8). However, the API documentation in the README is difficult for users to reference, and it seems generally not a good practice to manually write the specifications separately in both the API documentation and the docstring. To solve this problem, how about automatically generating an HTML-format API document from the docstring and hosting it on GitHub Pages?
Using pdoc3, you can easily generate HTML-format API documentation from docstrings in your code.
pip install pdoc3
pdoc3 ./pycircos -o ./pycircos_api_docs --html --force \
-c list_class_variables_in_index=False -c sort_identifiers=False
Example API docs: pycircos_api_docs.zip (:warning: some display is broken, docstring needs a little fixing)
After the automatic generation of HTML API docs, you can publish them to your users by simply placing the generated docs in a directory in your repository where GitHub Pages is enabled.
Example: GitHub Pages / Repo (<= I'll delete this example page in a few weeks)
You can also configure GitHub Actions to automatically update the API docs after a Push/Pull-Request to GitHub, if you are interested in trying this. If needed, I can provide an automated API docs generation workflow with GitHub Actions that I use.
The following article may be helpful (in Japanese).
- How to easily create documentation for your own python package and put it on github pages
- Using pdoc + GitHub Actions to automatically publish documentation to GitHub Pages
Best Regards,
I think this comment is fundamental!
Thank you for your advice, and I'm sorry for my late response.
I'm so busy now, but I will try to resolve this issue as soon as possible.