Add Github Pages using Sphinx documentation

[Lodewic]

Github Pages with Sphinx

This PR adds a Github Action to publish Github Pages, with documentation created with Sphinx and nbsphinx to allow writing pages with Jupyter notebooks.

The Preview hosted from my fork is here: https://lodewic.github.io/trelliscope-py/

Deploying using Github Actions

Added a new workflow that builds and publishes Sphinx documentation from a new ./docs directory.

Sphinx documentation

I am using Sphinx with the nbsphinx plugin. Sphinx is commonly used and can generate a classic 'read-the-docs` style for documentation. I also found bootstrap themes that are more similar to the TrelliscopeJS documentation - but they did not work for me out of the box.

For most of the codebase I intend to heavily autodoc and automodule. This will automatically document all the objects in a module, granted that they have a docstring in the first place. Docstrings are parsed and rendered automatically, but... this requires an agreed-upon style.

Docstring style

To make Sphinx documentation work with autodoc, we should choose one of 2 docstring-styles:

• google-style: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
• NumPy-style: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html

Personally I prefer the Google-style docstrings.

When being strict about type-hinting everything, types do not need to be included in the docstrings, which is nice. A good extension to handle type-hints with autodoc is this, https://pypi.org/project/sphinx-autodoc-typehints

About nbsphinx

Use Jupyter Notebooks to create documentation pages, largely for runnable examples. Documentation here: https://nbsphinx.readthedocs.io/en/0.9.3/

Using Jupyter notebooks to create documentation is quite powerful I think, and makes the example notebook you made instantly available in the documentation pages. I intend to create more example notebooks, both for users and for developers.

Additionally, when generating the documentation, the documentation notebooks are actually executed. Therefore I consider these a type of integration test, creating incentive to create documentation that executes most of the codebase. Also, by executing the notebooks in a workflow - and failing when any notebook fails - we ensure that all examples are in fact reproducible for users.

[hafen]

@Lodewic thanks this looks awesome!

I think google style is good.

@sburton42 let me know if you have any additional comments otherwise I am good to merge.

[Lodewic]

Hi @hafen, thank you! I am happy to hear you like it and feel like it is ready to merge

There are some additional changes that need to be made to the pages before they are complete, which is why I flagged this PR as a [Draft]. However, I try to avoid creating a single Huge PR that changes too many things at once.

Before merging this, I think it would be nice to have a better first version of the docs in place. To achieve that, I would first like to make a series of PR's that would be merged into this one. These would be PR's such as:

• Rewrite all docstrings to google-style format.
• Include all python modules in the API Reference section of the docs.
• Include a proper 'Quickstart' page with a small runnable example

Finally, before merging this, there are some Github repository settings that need to be configured for Github Pages to work. I don't have permissions to configure that but I am happy assist when the time comes.

[sburton42]

This all sounds great to me, including the use of the Google style. Thanks!

[hafen]

@Lodewic I agree and think it's great to go ahead with each of those bullets. Are these things you would be interested in contributing? I am happy to assist but would need some direction since my development involvement is mostly on the R/JS side.

[Lodewic]

@hafen I am definitely aiming to contribute the bulletpoints I stated. Hope to find time this weekend.

I saw you made updates to the JS side of things and it makes me wonder if there are other channels where you collaborate that I might join the conversation.

[hafen]

@Lodewic yes it would be great to add you to our slack channel. Send me a note at rhafen@gmail and I'll get you added. Thanks!

[Lodewic]

@hafen and @sburton42 , all the changes I wanted to implement for a first version of the docs are done!

Have a look and let me know what you think: https://lodewic.github.io/trelliscope-py/

1. Added docstrings to every function.
2. Added pydocstyle plugin for linting, which verifies that every public method and module has a google-style docstring.
3. Added more notebook examples, for Mars Rover, Gapminder and Iris datsets.
4. Removed the scripts from trelliscope.examples, since I created notebooks from them.
5. Added a get_example_data() method to load the included example datasets easily, as shown in the docs notebooks.
6. Ensured that all functions are shown in the 'API Reference' section of the docs

---

Now with:

• quick Iris data example to the "Quickstart"
• changed the theme to sphinx-book-theme. If you prefer the ReadTheDocs theme, let me know it's easily changed.
  • Or choose a theme here: https://sphinx-themes.readthedocs.io/en/latest/

[Lodewic]

To enable Github Pages for this repositoy, go to Settings -> Pages . Ensure Source = 'GitHub Actions.

Not every branch is set up to update the docs, this is configured under Settings -> Environments. I don't know yet how to host multiple versions of the docs, so I don't think you want feature branches to overwrite the Pages.