Closed speth closed 8 months ago
Merging #1631 (ba90868) into main (7eed1bd) will increase coverage by
0.00%
. The diff coverage isn/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%) |
:arrow_up: |
:mega: We’re building smart automated test selection to slash your CI/CD build times. Learn more
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
.
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
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!)
@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 https://github.com/Cantera/enhancements/issues/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).
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.
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.
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.
Changes proposed in this pull request
This PR implements the organizational structure for the website proposed and discussed in https://github.com/Cantera/enhancements/issues/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 https://github.com/executablebooks/MyST-NB/issues/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
cantera-website
)If applicable, provide an example illustrating new features this pull request is introducing
Checklist
scons build
&scons test
) and unit tests address code coverage