Skip to content

Update documentation system (migrate to Mkdocs) #562

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 124 commits into from
Oct 14, 2025
Merged

Update documentation system (migrate to Mkdocs) #562

merged 124 commits into from
Oct 14, 2025

Conversation

@matthewbbrandt
Copy link

@matthewbbrandt matthewbbrandt commented Jul 15, 2025 •
edited
Loading

Description

This PR updates the documentation system to use Material for Mkdocs. Overall, this PR aims to simplify the documentation system by reducing dependencies and updating to a well-maintained build tool which generates visually-appealing and user-friendly documentation. Some lesser-used features are also removed (e.g., docs can no longer be exported to a Latex document).

Future work could include:

  • Finishing the type map, which maps between a type and the user-friendly string that is rendered (e.g., "FLOAT" -> "number"). As of this PR, only a few types have been added to the map.
  • Evaluating if the Python dependency should be moved to the parent CSE directory, rather than living only in the doc folder.
  • Implementing a coverage check, which is available in the current documentation system but has not yet been implemented for the new system.
  • Deploying multiple versions of the docs, so users can review both the latest and pervious versions of the documentation. This is supported by Material for Mkdocs for GitHub pages using mike as the versioning provider.

Author Progress Checklist:

  • Open draft pull request
    • Make title clearly understandable in a standalone change log context
    • Assign yourself the issue
    • Add at least one label (enhancement, bug, or maintenance)
    • Link the issue(s) addressed by this PR (under "Development" in the sidebar menu)
  • Make code changes (if you haven't already)
  • Self-review of code
    • My code follows the style guidelines of this project
    • I have added comments to my code, particularly in hard-to-understand areas
    • I have only committed the necessary changes for this fix or feature
    • I have made corresponding changes to the documentation
    • My changes generate no new warnings
    • I have ensured that my fix is effective or that my feature works as intended by:
      • exercising the code changes in the test framework, and/or
      • manually verifying the changes (as explained in the the pull request description above)
    • My changes pass all local tests
    • My changes successfully passes CI checks
    • Add any unit test for proof and documentation.
    • Merge in main branch and address resulting conflicts and/or test failures.
  • Move pull request out of draft mode and assign reviewers
  • Iterate with reviewers until all changes are approved
    • Make changes in response to reviewer comments
    • Merge in main branch and address resulting conflicts and/or test failures.
    • Re-request review in GitHub

Reviewer Checklist:

  • Read the pull request description
  • Perform a code review on GitHub
  • Confirm all CI checks pass and there are no build warnings
  • Pull, build, and run automated tests locally
  • Perform manual tests of the fix or feature locally
  • Add any review comments, if applicable
  • Submit review in GitHub as either
    • Request changes, or
    • Approve
  • Iterate with author until all changes are approved

Matthew Brandt added 30 commits February 20, 2025 21:45
Initial commit for migration to Mkdocs.
2a2198e 
- Adds uv for python environment and dependencies.
- Removes all ruby/pandoc content.
- Begins adding configuration for Mkdocs based on other BLS Mkdocs projects.
- Remaining work includes fixing internal links, tables, and probes.
Restore markdown from previous pandoc/ruby version to better track ch…
1771f79 
…anges in git.
Add autorefs plugin and translate links for use with the plugin.
dc51d3c
Use autorefs for the few outliers that were remaining.
9a4681b
Remove unused dependencies and alphabetize plugins.
016e8bd
Add custom js for Katex rendering.
cf82367
Clean up index file.
67be4bc
Reset tables in input-data index.md (will be updated with mkdocs macr…
03b63c6 
…os in a future commit).
Reset input data folder.
467fc24 
I previously had prettier running on save, but it made several undesired changes, such as sometimes replacing "member_table" with "member*table".
Restore autoref syntax for links.
6e0b22b
Replace insert_file functionality with mkdocs-macros' include statement.
a93a9a9
Move unused files to extra folder.
38fcede 
Can these be deleted?
Add (draft) version of csv_table and member_table functions.
0030d1d
Update syntax for (most) member tables.
0c001f4
Update syntax for tables missing one of the five member_table keys.
d8c749f
Fix previously broken link.
e4482db
Update syntax for (most) csv tables.
6e4a0fe
Remove inner quotations for csv_table string.
91387fd
Avoid adding sort buttons for tables with only two rows.
f78c21d
Add degree symbol for member tables with unit of F (should be degF).
bd1f460
Use csv_table instead of importing from a file.
fbe973f
Add support for csv_table_from_file.
cb15bbe
Refactor main.py to use pathlib.Path instead of os.path.
01e78fb
Remove backslashes that trigger deprecation warnings (address two of …
36d70f0 
…five: "\$" and "\ ").
Update dependencies.
db37d66
Remove table-reader from mkdocs plugins.
2fed8f7
Remove unused f prefix.
6d4a1ec
Delete probe-1 junk file.
3ad0801
Add probe definition MD files, other than index.md to gitignore.
09b065f 
We may decide to revert this in the future, depending on how/when we build the docs for deployment to gh-pages.
Add awesome nav to plugins to extract nav properties from mkdocs.yml.
9088778
Matthew Brandt and others added 16 commits September 16, 2025 15:39
Install mkdocs-material research-preview-2 for improved search behavior.
ee13bcf
Merge branch 'main' into feature/migrate-to-mkdocs
41f198f
Merge remote-tracking branch 'origin/rsys-plr' into feature/migrate-t…
cdb4bf9 
…o-mkdocs
Merge remote-tracking branch 'origin/transmitted-solar' into feature/…
9ffaa0a 
…migrate-to-mkdocs
Restore line-breaks required for docs parser.
90d2f64
Add accumulator to input-data nav.
0b3f3de
Update syntax for member tables and use MD headings for member names …
6f1203a 
…in new accumulator.md file.
Merge branch 'main' into feature/migrate-to-mkdocs
0d1619f
@nealkruis
Automate documentation generation through CMake.
6d2e342
@nealkruis
Add doc CMake file.
ec62514
@nealkruis
Fix defined argument passed to CMake command.
d6ef563
@nealkruis
Make distinct document uploads for each runner.
6c6d2be
@nealkruis
Clean up invalid escape character warnings.
7da379e
@nealkruis
Use unicode degree symbols.
7dfdee9
@nealkruis
Clean up dated and obsolete documentation.
89975e8
@nealkruis
Merge remote-tracking branch 'origin/main' into feature/migrate-to-mk…
23ee765 
…docs
@nealkruis nealkruis linked an issue Oct 7, 2025 that may be closed by this pull request
Documentation system support for arbitrary hyperlinks #528
Closed
@nealkruis nealkruis mentioned this pull request Oct 7, 2025
Closed
@nealkruis nealkruis marked this pull request as ready for review October 14, 2025 14:54
@nealkruis nealkruis merged commit d299460 into main Oct 14, 2025
3 checks passed
@nealkruis nealkruis deleted the feature/migrate-to-mkdocs branch October 14, 2025 15:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@nealkruis nealkruis nealkruis approved these changes

@chipbarnaby chipbarnaby Awaiting requested review from chipbarnaby

Assignees

@matthewbbrandt matthewbbrandt

Labels

documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Documentation system support for arbitrary hyperlinks

4 participants

@matthewbbrandt @chipbarnaby @nealkruis