Change HTML generator to Sphinx #209
Description
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.pyformat - 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, orMyST. 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.