Open bryanwweber opened 2 years ago
@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
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.
@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
.
Thanks @anthony-walker, this is still ongoing work in the branch I linked above: website-reformat-myst-sphinx
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
conf.py
formatNon-Goals
doxylink
,breathe
, orMyST
. These will be added and tracked separately.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](https://myst-parser.readthedocs.io/en/latest/index.html) 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.