Change HTML generator to Sphinx

[bryanwweber]

Since this website was redesigned in 2018, the tradeoffs that led us to choose Nikola at that time have shifted in favor of using Sphinx. This issue will track the progress of moving the HTML generation of the cantera-website repository to use Sphinx instead of Nikola.

Action Items

• Use Sphinx conf.py format
• Ensure examples can be generated
• Move content files as needed to support Sphinx's directory layout

Non-Goals

• Modify or add any content. It may be necessary to move content files around to support Sphinx, but we do not intend this to be significant modifications to the content, or structure of the content, of the site.
• Add plugins or parsers to support content that is not already on the site. Specifically, this work is not intended to add new plugins like doxylink, breathe, or MyST. These will be added and tracked separately.
• Simplifying linking to content beyond that provided by built-in Sphinx functions for content in this repository. Specifically, I anticipate that we can make linking to the Python API significantly easier because everything will be done by Sphinx.
• Modify the theme. To the extent possible, we do not want to modify the theme of the site in this issue. This is a loose requirement; it may be easier to switch the theme to the PyData theme at this time, but I hope we can keep that out-of-scope.

As the necessary plugins will be changing in this switch, this issue supersedes #22

Further context can be found by expanding this section.

In 2018, we re-designed the Cantera documentation and website using Nikola as the HTML generator for the bulk of the content, and retained Sphinx to generate API documentation in Cantera/cantera. At the time, this was justified on the basis that Nikola would be better suited to generate purely static content.

However, our experience is that mixing Nikola and Sphinx is more challenging than helpful. Specifically, the custom plugins that we implemented to replace parts of Sphinx's functionality for linking to other sections and documentation are not very robust, and since they're not documented, making updates or even just learning how to use them in prose is difficult. On the other hand, Sphinx roles are well known features and are well documented, so using Sphinx throughout will allow us to eliminate these custom Nikola plugins.

Second, the last 4 years have seen the development of fairly advanced Sphinx themes targeting the PyData community, specifically https://github.com/pydata/pydata-sphinx-theme. By switching to Sphinx, we can use this theme and eliminate many of the theme customization we developed for Nikola, including the custom Bootstrap directives.

Finally, there is a new markup syntax, MyST that offers the best of Markdown and reST mashed together. As they have native integration with Sphinx, we can easily use this markup by changing everything to Sphinx.

[bryanwweber]

@chinahg I created a branch website-reformat-sphinx-myst that we can base our changes on. I think if we make pull requests against that branch, we can avoid messing up the existing site while the changes are ongoing.

The short instructions:

git fetch upstream
git switch website-reformat-sphinx-myst
git switch -c <a-new-branch-for-more-work>

The README on that branch should have instructions to be able to build the site with Sphinx

[bryanwweber]

I'm going to work on the examples, making sure those can be displayed properly. @chinahg if you want to work on making sure content is formatted correctly (links, section labels, etc.), that'd be a great place to start, related to #210 and #211 as well.

[anthony-walker]

@bryanwweber This will hopefully resolve the issues with docutils as well. nikola results in broken links when using docutils>0.16 but for cantera to build docs using sphinx it requires docutils>=0.18.

[bryanwweber]

Thanks @anthony-walker, this is still ongoing work in the branch I linked above: website-reformat-myst-sphinx