Repository navigation
Conversation
…older requirements-sphinx.txt is requirements.txt and gen_api_pages_sphinx.py is gen_api_pages.py, the names used by the other sites. The scripts are copies of docs-site/scripts in CompMetEng/skills; names, paths and categories are in scripts/project.yml. The API pages now show signatures and render numpydoc sections, list the same functions as before, and no longer carry the MkDocs icon front matter. conf.py follows the standard: smartquotes off, the cobrapy inventory and the guide linker, and a link check setting. Logos and the favicon are in docs/_static only, with a white logo for dark mode made from the green one (every pixel white, alpha kept, as for gecko-icon-white.png); docs/assets is removed.
The home page classes are site-* instead of gd-*, and the home page has one logo per colour scheme. The two greens in use (#43684B for tabs and borders, #2D6E3B for links and the badge, with the dark-mode values) are set as --pst-color-primary, --pst-color-link and --site-accent.
docs-build.yml runs scripts/check_site.py, a build with -W, the function name check and a link check on pull requests, on pushes to main and weekly. Read the Docs fails on warnings too. The name check and the link check do not block yet: 124 distinct names on the guide pages are unresolved and the external links were not checked. The submodule update opens a pull request instead of pushing to main; this needs the repository setting that allows GitHub Actions to create pull requests.
…Dependabot CONTRIBUTING.md has the same writing rules as before plus the build commands and the reference to the docs-site standard. Dependabot updates the pip and GitHub Actions dependencies weekly.
…lugin The name check keeps deprecated Python aliases, which the reference pages leave out, so the guide pages can name an alias on purpose. The scripts were copied before that change.
DESIGN.md records the purpose, structure, differences from the standard (mathjax), open items and the decisions of this alignment. The README names the new files and scripts, describes the strict build and drops the em dashes and the link to the old raven-docs location. Four guide pages that explain a concept or a format are marked as concept pages, so they need no function table.
Documentation build overview
44 files changed ·
|
The dark-mode logo is a decision in the log and no longer an open question.
…bs and visits sphinx-design links the tabs of a page and carries the choice to the next page, but keeps it in sessionStorage, so a new browser tab or a later visit started in MATLAB again. language-sync.js stores the language in localStorage, applies it to every tab set when a page loads and when the reader switches, and follows a switch made in another open tab. The install tabs, which have no sync key, select the first tab named after the language.
The site check now requires language-sync.js and its entry in conf.py.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follows the docs-site standard of CompMetEng/skills#6, which raven-docs follows too.
requirements-sphinx.txtisrequirements.txtandgen_api_pages_sphinx.pyisgen_api_pages.py, the names raven-docs uses.scripts/: copies ofdocs-site/scripts. Everything that named GECKO is inscripts/project.yml. The API pages list the same functions as before; they now show signatures and render the numpydoc sections (Parameters,Returns) as in raven-docs, and the MkDocsicon:front matter is gone. The guide pages get links from function names to the API reference and to cobrapy.docs/conf.pyfollows the standard: straight quotes in the API pages, the cobrapy inventory, the link check settings, andsphinx.ext.mathjaxfor the equations.docs/_static/custom.cssanddocs/index.md: the shared stylesheet, with the two greens in use. The home page classes aresite-*.docs/_static/language-sync.js: the language of the code tabs is remembered. A switch between MATLAB and Python applies to every tab on the page, to the next pages, to new browser tabs and to later visits, and the install tabs follow it. sphinx-design alone linked the tabs of a page and carried the choice to the next page in the same browser tab only, because it keeps it insessionStorage. Checked in a browser on the built site.docs/_static/gecko-logo-white.pngis made fromgecko-logo.pngby making every pixel white and keeping the alpha channel, the waygecko-icon-white.pngwas made. Logos and the favicon are indocs/_staticonly;docs/assetsis removed, including the unusedgecko-icon-color.pngandgecko-icon-white.png..readthedocs.yamland.github/workflows/docs-build.yml: the build fails on warnings. The workflow also runsscripts/check_site.py, the name check and a link check. The name check and the link check do not block yet..github/workflows/update-submodules.ymlopens a pull request instead of pushing tomain.DESIGN.mdis new.README.mdhas the new file names, and the em dashes and the link to the old raven-docs location are gone.CONTRIBUTING.md, a pull request template and Dependabot are added. Four guide pages that explain a concept or a format are marked as concept pages.Open: 121 distinct names on the guide pages are neither functions of the toolboxes nor allow-listed (
scripts/check_names.py). Most are keyword arguments, struct fields and YAML keys; someone who knows the pages has to sort them before the check can block. Needed outside the repository: "Build pull requests for this project" in the Read the Docs settings, and the GitHub setting that allows Actions to create pull requests.