Website structure update

[speth]

Changes proposed in this pull request

This PR implements the organizational structure for the website proposed and discussed in Cantera/enhancements#178.

Currently, a handful pages have been migrated from cantera-website to help visualize the structure and test the new plugins (mainly, myst-nb). The one section I transferred in full so far is the compilation instructions. I've added admonitions redirecting users back to the current site in the meantime.

The introduction of the myst-nb dependency as temporarily pushed us back to Sphinx 5.3 (we were on 6.x), until they can sort out a a new release. There are several other projects in the same boat regarding this dependency; see executablebooks/MyST-NB#543.

Before this is merged, we will need to update the dev docs landing page at https://cantera.org/documentation/dev-docs.html by merging Cantera/cantera-website#258. I'm leaving this PR as a "draft" until that's ready so we don't merge it prematurely.

You can see the full website built from this branch (and the corresponding branch of cantera-website) at https://testing.cantera.org.

If applicable, fill in the issue number this pull request is fixing

• Progress toward Use MyST as the markup format cantera-website#211
• Progress on Allow access to latest documentation version through stable URL cantera-website#229
• Effectively resolves Consolidate works cited enhancements#145 (moving individual citations will happen as content is moved in from cantera-website)

If applicable, provide an example illustrating new features this pull request is introducing

Checklist

• The pull request includes a clear description of this code change
• Commit messages have short titles and reference relevant issues
• Build passes (scons build & scons test) and unit tests address code coverage
• Style & formatting of contributed code follows contributing guidelines
• The pull request is ready for review

[codecov]

Codecov Report

Merging #1631 (ba90868) into main (7eed1bd) will increase coverage by 0.00%.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #1631   +/-   ##
=======================================
  Coverage   72.71%   72.72%           
=======================================
  Files         370      370           
  Lines       56286    56286           
  Branches    20369    20369           
=======================================
+ Hits        40931    40932    +1     
+ Misses      12358    12357    -1     
  Partials     2997     2997           

Files	Coverage Δ
include/cantera/zeroD/Reactor.h	61.76% <ø> (ø)
interfaces/cython/cantera/_utils.pyx	91.92% <ø> (ø)
interfaces/cython/cantera/thermo.pyx	93.25% <ø> (+0.13%)	⬆️

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[ischoegl]

I downloaded the artifacts and things looks promising to me.

While I realize that most of the overview pages are stubs, I do like the way the Reference navigation works a lot (i.e. cards look really nice, as they avoid the duplication of the left-hand side tree). As an aside, the Community tab link is broken, but this may be something that is populated in the website.

@bryanwweber ... I know that you have limited bandwidth, but in terms of how this integrates into the website your opinion weighs more than mine.

[speth]

As an aside, the Community tab link is broken, but this may be something that is populated in the website.

Yes, this is expected. It is a link to /community.html, which when this is deployed to cantera.org will link to https://cantera.org/community.html. There are several other links back to the current site that will be "broken" when viewing these generated docs without the content of cantera-website.

[bryanwweber]

Is this a comment format for md?

[speth]

Yes, for MyST-flavored Markdown, at least.

[bryanwweber]

I know that you have limited bandwidth, but in terms of how this integrates into the website your opinion weighs more than mine.

@ischoegl thanks for your faith in me 😊 but I don't think I have a special perspective here. Overall the reorg seems reasonable to me

[ischoegl]

@speth ... I saw that you pushed some revisions, so I downloaded the artifacts again. This time I have a couple of small suggestions:

• Eliminate Develop dropdown, and move the 'installation from source' to Install, and the remaining two items 'how Cantera works' and 'adding models' to the User Guide
• Improve landing pages for Examples and Install by using cards (similar to Reference). While the underlying items are work in progress, the structure used for the main features is mostly known.
• It may make sense to add a separate FAQ section on the Install section, so it will be easier to find.

[speth]

Eliminate Develop dropdown, and move the 'installation from source' to Install, and the remaining two items 'how Cantera works' and 'adding models' to the User Guide

This section is admittedly a bit nebulous at the moment, since it's all new content except for the compilation instructions. My goal is to provide a range of resources for potential contributors. Taking a broad view of "How Cantera Works", I'm anticipating things like a description of our PR process, style guidelines, recommended tools (possibly just a link to the https://github.com/Cantera/dev-tips repo), and description of our various packaging workflows, in addition to explanations on some of the library code like how factories or the MultiRate system work. This is all pretty far removed from what I think makes sense for the "User Guide", though perhaps a some links into this section would be useful. Either way, we have some time to reconsider this structure -- I don't think it's locked in at all until the next release.

Improve landing pages for Examples and Install by using cards (similar to Reference). While the underlying items are work in progress, the structure used for the main features is mostly known.

I agree that cards would work well for the Examples landing page. For the Install landing page, I was planning to keep the structure we're currently using on https://cantera.org/install/, which I think works pretty well. I don't think cards would work as well for directing users to the best installation option.

It may make sense to add a separate FAQ section on the Install section, so it will be easier to find.

Certainly, a link to a section of installation-related questions in the FAQ from the Install section makes sense. But first, we need to write some questions (and answers!)

[ischoegl]

@speth thanks for the thoughts. One reason why I think it would still make sense to eliminate Develop is that the top line is already somewhat crowded, with some non-ideal rendering on smaller screens. Example: on my MacBook Pro, anything less than about 2/3 screen width doesn't look great:

I am especially concerned about rendering on tablets (which I am unable to check).

This section is admittedly a bit nebulous at the moment. [...] This is all pretty far removed from what I think makes sense for the "User Guide", though perhaps a some links into this section would be useful. [...]

Personally, I'm not necessarily convinced that there is a clear separation between User Guide and Develop. My own thoughts for this in Cantera/enhancements#183 were to provide much of the 'under the hood' comments in Doxygen md's (in essence, letting Doxygen handle developer content and provide links from the main site), but that's certainly debatable.

Regarding the current layout of Install, I believe that a hybrid of cards and current layout (summarizing several items under a Linux Packages card) may still be better (ideally, pip and especially conda should be visually prominent so we steer new users towards what is recommended).

[ischoegl]

Fwiw, I think the crowded header line issue is something that can be optimized by other means. I just looked at SciPy and their layout works pretty well (I believe they use the pydata theme as well). I guess their 'Development' tab is close to what you were envisioning? Regardless, all of this can be tweaked at a later point.

[ischoegl]

Thanks @speth. Overall, I view this as work in progress. If the 'draft' is by accident and you want to merge, please feel free to do so.

[speth]

One reason why I think it would still make sense to eliminate Develop is that the top line is already somewhat crowded, with some non-ideal rendering on smaller screens. Example: on my MacBook Pro, anything less than about 2/3 screen width doesn't look great:

I made some CSS tweaks so that as the page gets narrower, we hide the placeholder text in the "search" box and collapse the Cantera logo to just the icon part (i.e., no text). This allows all of the headings to appear in a single line until the theme switches to the next layout where the headings are collapsed into a hamburger. You can get an idea of what the page would look like on a tablet (or even a phone) by just continuing to make the page narrower. Everything is done by using a "responsive" CSS layout, handled almost entirely by pydata-sphinx-theme.

I just looked at SciPy and their layout works pretty well (I believe they use the pydata theme as well). I guess their 'Development' tab is close to what you were envisioning? Regardless, all of this can be tweaked at a later point.

Yes, they are also using the PyData theme. I guess one difference is that they've moved the "Search" box into the left navigation area rather than the top, which gives some extra space. And yes, the SciPy "development" section is very much what I'd like to aim for eventually having in our "Develop" section.

Regarding the current layout of Install, I believe that a hybrid of cards and current layout (summarizing several items under a Linux Packages card) may still be better (ideally, pip and especially conda should be visually prominent so we steer new users towards what is recommended).

Well, if you're volunteering to handle this section, by all means 😁. I would hesitate to direct users too strongly to Pip, since it has some significant limitations (lack of HDF5 support, and not built with optimized BLAS/LAPACK libraries on most systems).

If the 'draft' is by accident and you want to merge, please feel free to do so.

The 'draft' status is to avoid merging this until Cantera/cantera-website#258 is also merged.

[bryanwweber]

You can get an idea of what the page would look like on a tablet (or even a phone) by just continuing to make the page narrower.

You can also set a specific resolution from specific phones in the Dev tools which also constrains the height and doesn't screw with the window size.