Generate HTML documentation from docstring comments

[jcassady]

Description: The goal of this issue is to leverage docstring comments in the source code to automatically generate HTML documentation pages for GitHub Pages. By doing so, we can provide clear and accessible documentation for users and contributors.

Proposed Solution:

1. Docstring Parsing: We need a tool that can extract docstrings from the Python source code. One option is to use the sphinx-markdown-builder Python module, which integrates with Sphinx to generate Markdown documentation from docstrings. This will allow us to create Markdown files that can be easily converted to HTML.

2. GitHub Actions Workflow:

   • Set up a GitHub Actions workflow that triggers on pushes to the main branch or when new commits are made.
   • Use the Sphinx tool to build the HTML documentation from the docstrings.
   • Deploy the generated HTML files to GitHub Pages.

Additional Resources:

• GitHub Actions Documentation
• Sphinx Documentation

[nickterhaar]

I think pdoc (https://pdoc3.github.io/pdoc/) could also be a solution for this.

Pdoc generates html directly of all docstrings and follows module hierarchy. Don't know if it also works with GitHub Actions Workflow, no experience with that (yet).

[jcassady]

Hi @nickterhaar, I'll take a look at pdoc. However, I just merged @gdevakumar's PR adding phinx documentation support: https://github.com/jcassady/llava-benchmark/pull/10

It looks like adding a github workflow to generate the html on pushes to the main branch is easy, so I'll get that setup soon.

[jcassady]

I added .github/workflows/docs.yml to generate the html from the .rst files that Sphinx creates, then deploy to GitHub Pages:

https://jcassady.github.io/llava-benchmark/

[jcassady]

@gdevakumar Would you be able to share the steps you used to create the .rst files with phinx? I had an issue generating the index.rst file when I gave this a go.

[gdevakumar]

@jcassady , these are the steps i followed:

1. Install sphinx using pip install sphinx sphinx-rtd-theme
2. mkdir docs
3. cd docs
4. sphinx-quickstart and proceed with defaults
5. Modify docs/conf.py, docs/index.rst files as shown in the commit
6. sphinx-apidoc -o . ..
7. make html

This will generate all the relevant docs!

[jcassady]

Thanks for sharing @gdevakumar!