Skip to content

About

FEAScript Documentation

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

FEAScript Logo

FEAScript-documentation

User and developer documentation for the FEAScript project, published at docs.feascript.com. Built with Docusaurus (Node.js >= 20).

Local development

npm install
npm start        # dev server with live reload
npm run build    # production build into ./build
npm run serve    # serve the production build locally

Previewing the site locally

  1. Start the dev server with npm start and open http://localhost:3000. Pages reload as you edit them. Only the current docs are built up front, so the first switch to an older version in the dropdown takes a few seconds.
  2. Before merging, build and serve the production site with npm run build && npm run serve, and open http://localhost:3000 again. The build fails on broken links, which the dev server does not check.

The current docs are served at / (for example http://localhost:3000/verification/overview) and the snapshots at /<version>/ (for example http://localhost:3000/0.3.1/).

Docusaurus needs Node.js 20 or newer. With an older Node.js, run the same commands through a temporary Node.js 20 from npm, without installing it:

npx -y -p node@20 -c "npm start"
npx -y -p node@20 -c "npm run build && npm run serve"

Writing docs

  • Pages are Markdown/MDX files under docs/; the sidebar is defined in sidebars.js.
  • Math is supported with KaTeX: inline $T$ and block $$ ... $$.
  • Figures are black line-art SVGs in static/assets/, inverted in dark mode. The figures of the verification and example pages are generated by scripts that share their drawing style (scripts/figure_style.py); rerun them when a test or an example changes:
    • Verification: python3 scripts/generate-verification-figures.py, which reads the Gmsh meshes from ../FEAScript-core/tests/meshes.
    • Examples: node scripts/export-example-results.mjs runs the Node.js examples of ../FEAScript-core (built with npm run build) unchanged and records their meshes and solutions; then python3 scripts/generate-example-figures.py draws the geometries, meshes and results.
    • Log-log plots (convergence, comparison with Elmer, solver times): python3 scripts/generate-plot-figures.py. Their values are those of the tables next to each plot; update both together.
  • docs/ always holds the docs of the current FEAScript-core version ("0.4.0" in the version dropdown).
  • static/llms.txt (served at docs.feascript.com/llms.txt) is a hand-written, single-file API summary for AI assistants. Update it whenever the API changes: new models, options, boundary conditions or solvers.

Appearance

The theme follows the design tokens of feascript.com: cream "engineering paper" with a blueprint grid, charcoal ink, gold accent, a floating pill navbar, always-dark code blocks, and Roboto / Roboto Mono, with a matching dark mode. The footer uses the website's footer color (#f6efd9, #222222 in dark mode). Colors and component styling live in src/css/custom.css; fonts and the code theme are set in docusaurus.config.js.

The navbar's GitHub pill matches the website and fetches the FEAScript-core star count from the public GitHub API in the browser. If the request fails, the link remains usable without a count and the error is logged to the browser console.

Versioning

The docs keep one version per minor release of FEAScript-core (MAJOR.MINOR), labeled with its latest patch release. Patch releases do not change the API, so they get no docs version of their own.

  • docs/ holds the docs of the latest minor version and is served at the unversioned URLs (lastVersion: "current" in docusaurus.config.js). Its label in the version dropdown is set in docusaurus.config.js.
  • Older minor versions are snapshots in versioned_docs/version-x.y.z/, served at docs.feascript.com/x.y.z/..., with their sidebars in versioned_sidebars/ and their names in versions.json.

Patch release (for example 0.3.1 → 0.3.2): update the docs in docs/ if needed and change the label of current in docusaurus.config.js to the new version.

Minor or major release (for example 0.3.x → 0.4.0): before changing docs/, snapshot it under the latest patch release of the previous minor version:

npm run version -- 0.3.1

This copies docs/ to versioned_docs/version-0.3.1/, the sidebar to versioned_sidebars/, and records the version in versions.json. Then add the snapshot to versions in docusaurus.config.js (with banner: "unmaintained"), change the label of current to the new version, and update docs/ for the new release.

Versions appear inside the dropdown, not as separate links across the navbar. The space between the logo and the right-hand controls is flexible layout spacing.

Fixes to an old version are made directly in its versioned_docs/version-x.y.z/ folder. Absolute links in those pages, such as CDN URLs and examples, must point to that version (for example [email protected] and the 0.2.0 tag of FEAScript-core), not to the latest release.

Deployment

Pushing to main triggers .github/workflows/deploy.yml, which builds the site and deploys it to docs.feascript.com.

The build also writes sitemap.xml, with every page and a <lastmod> from the page's last git commit (the same date as the "Last updated" line under each page), so it needs no manual editing. The workflow checks out the full git history for these dates; a shallow clone would give every page the date of the last commit. static/robots.txt points search engines to the sitemap.

License

The content of the FEAScript documentation is licensed under CC BY 4.0. Note that the core library of FEAScript is distributed under the terms of the MIT license.

The CC BY 4.0 license does not cover the FEAScript logo or the name "FEAScript", which are not licensed. You may use them unchanged when you refer to FEAScript, for example in a lesson, a talk or a blog post; for anything else, please ask first at [email protected].

About

FEAScript Documentation

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Sponsor this project

Contributors

Languages