Suggestions for Improvements of API Documentation

[moshi4]

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,

[Mickychen00]

I think this comment is fundamental!

[ponnhide]

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.

[moshi4]

There is no particular need to rush, so you are free to deal with this issue at your own pace. I created PR (#17) myself to resolve this issue, so please check it out when you have time.