-
Notifications
You must be signed in to change notification settings - Fork 26
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Change HTML generator to Sphinx #209
Comments
@chinahg I created a branch The short instructions:
The README on that branch should have instructions to be able to build the site with Sphinx |
@bryanwweber This will hopefully resolve the issues with |
Thanks @anthony-walker, this is still ongoing work in the branch I linked above: |
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 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.
The text was updated successfully, but these errors were encountered: