Skip to content
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

Website structure update #1631

Merged
merged 22 commits into from
Oct 9, 2023
Merged

Website structure update #1631

merged 22 commits into from
Oct 9, 2023

Conversation

speth
Copy link
Member

@speth speth commented Oct 3, 2023

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

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
Copy link

codecov bot commented Oct 3, 2023

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

@speth speth requested a review from a team October 6, 2023 16:59
Copy link
Member

@ischoegl ischoegl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

doc/sphinx/install/conda.md Outdated Show resolved Hide resolved
doc/sphinx/install/pip.md Outdated Show resolved Hide resolved
@speth
Copy link
Member Author

speth commented Oct 6, 2023

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.

all examples covering a particular topic, regardless of programming language, select
from the {ref}`list of example tags <tagoverview>`.

% The following pages are generated by sphinx-gallery
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a comment format for md?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, for MyST-flavored Markdown, at least.

@bryanwweber
Copy link
Member

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

Copy link
Member

@ischoegl ischoegl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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
Copy link
Member Author

speth commented Oct 8, 2023

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
Copy link
Member

ischoegl commented Oct 8, 2023

@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:

image

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).

Copy Doxygen output into a subdirectory of Sphinx so the Sphinx
index can be the full site index.

Partially addresses Cantera/cantera-website#229
@ischoegl
Copy link
Member

ischoegl commented Oct 9, 2023

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
ischoegl previously approved these changes Oct 9, 2023
Copy link
Member

@ischoegl ischoegl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member Author

speth commented Oct 9, 2023

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
Copy link
Member

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.

@speth speth marked this pull request as ready for review October 9, 2023 19:16
@speth speth merged commit de77fa3 into Cantera:main Oct 9, 2023
41 checks passed
@speth speth deleted the website-structure branch October 9, 2023 21:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Consolidate works cited
3 participants