Update documentation

[hgscott]

Hosting documentation for a Python package on GitHub can be done using various methods, but one of the most popular and effective ways is by using GitHub Pages along with a documentation generator like Sphinx. Here's a step-by-step guide on how to achieve this:

1. Setup Sphinx Documentation:
   • Install Sphinx using pip: pip install sphinx.
   • Navigate to the root directory of your Python package in the terminal.
   • Run sphinx-quickstart to set up the documentation structure.
   • Configure the settings in conf.py to match your project.
2. Generate Documentation:
   • Write your documentation using reStructuredText (.rst) files in the source directory.
   • Run sphinx-build -b html source build in the terminal to generate the HTML documentation in the build directory.
3. GitHub Repository Setup:
   • Push your documentation files, including the generated HTML files, to a docs directory in your GitHub repository.
4. Enable GitHub Pages:
   • Go to your GitHub repository's settings.
   • Scroll down to the GitHub Pages section.
   • Select the main branch (or another relevant branch) as the source for GitHub Pages.
   • Choose the /docs folder as the root directory for GitHub Pages.
5. Accessing Documentation: -Once GitHub Pages is enabled and the build is successful, your documentation will be accessible at a URL like https://.github.io/.
6. Automate Documentation Builds (Optional):
   • You can set up automated documentation builds using GitHub Actions. This way, whenever you push changes to your documentation or code, the documentation will be automatically rebuilt and updated on GitHub Pages.
7. Custom Domain (Optional):
   • If you have a custom domain, you can configure GitHub Pages to use that domain for your documentation. Keep Documentation Updated:

As you make changes to your package or its documentation, remember to update the documentation source and regenerate the HTML files. By using Sphinx and GitHub Pages, you can create and host comprehensive and user-friendly documentation for your Python package. Additionally, there are alternative documentation generators like MkDocs and Read the Docs that you might consider if they better match your needs.

[hgscott]

To build everything inside of the docs folder, I had to run sphinx-build -b html docs/source docs/build

[hgscott]

I have almost everything working to generate the docs from the doc strings, but I am getting these two errors:

/Users/helenscott/Documents/PhD/Segre-lab/cometspy/cometspy/layout.py:docstring of cometspy.layout.layout.add_external_reaction:16: WARNING: Inline strong start-string without end-string.
/Users/helenscott/Documents/PhD/Segre-lab/cometspy/cometspy/layout.py:docstring of cometspy.layout.layout.set_region_map:6: ERROR: Unexpected indentation.

[hgscott]

I asked ChatGPT what these error messages mean, and I got this response:

The error messages you're encountering while building your Sphinx documentation relate to issues with the formatting of your docstrings in the Python module cometspy.layout.layout. Let's break down each error message:

WARNING: Inline strong start-string without end-string: This warning typically indicates that there's a formatting issue within your docstring, specifically around the use of inline markup. An "inline strong start-string" refers to a bold or strong text element, which is typically marked using double asterisks (**). The warning suggests that there is an unbalanced use of these markers, possibly missing an end-marker.

Check your docstrings for instances where you might have used double asterisks for bold text, and make sure they are properly balanced with opening and closing markers. For example, bold text.

ERROR: Unexpected indentation: This error message suggests that there is a problem with the indentation in your docstring. It's likely that there is an indentation inconsistency in the line mentioned in the error.

Make sure that the indentation within your docstrings follows the consistent indentation level of your code. Ensure that you're not mixing spaces and tabs for indentation, as that can sometimes cause unexpected behavior.

To resolve these issues:

For the warning about inline strong start-strings, review your docstrings and ensure that any inline markup (bold, italics, etc.) is properly balanced with opening and closing markers.

For the error about unexpected indentation, go to the line specified in the error message and check for indentation inconsistencies. Make sure the indentation in your docstrings matches the surrounding code.

Remember that proper reStructuredText (reST) formatting is crucial for Sphinx to correctly parse and render your documentation. Double-check your docstrings for any formatting issues and correct them accordingly.

[hgscott]

There was indeed an unbalanced ** in line 240: So I removed that.

[hgscott]

And I think the indentation error was because of the indented numbered list on lines 193 and 194: So I made the numbers flush with the text above it.

[hgscott]

And that gave me no errors, when I built the HTML files!

[hgscott]

Okay! Documentation is being generated and pushed to the website correctly!

[hgscott]

Next, I want to make the index page more helpful/welcoming. Where do I write that so that it is not overwritten in the rst files everytime I build?

[hgscott]

Playing around locally, it looks like the index.rst file doesn't get generated from anything, so I can just edit that file and it will stay that way until I change it again.

[hgscott]

The set-up is all done, but it would be nice to have a template/set of best practices for writing the docstrings to get the best documentation.