Skip to content

Mkdocs Enhancements#857

Merged
pgbrodrick merged 6 commits into
isofit:devfrom
jammont:mkdocs/mike
Feb 12, 2026
Merged

Mkdocs Enhancements#857
pgbrodrick merged 6 commits into
isofit:devfrom
jammont:mkdocs/mike

Conversation

@jammont

@jammont jammont commented Feb 10, 2026

Copy link
Copy Markdown
Collaborator

Now that the docs are building and hosted properly, this PR further enhances the UX

  • Added mike addon that will enable us to version control our docs

    • Expanded the workflow to auto tag docs with isofit versions on pushes to main, where these will be alias tagged as latest. Dev branch will also build docs with no version, simply named "dev"
  • Changed the theme from ReadTheDocs to Material

    • This theme has a lot of fancy features to it that can make our docs look a lot more professional, such as proper note/warning blocks, instant page loading, and switching between light and dark modes (along with automatic, which switches to light during day and dark during night)
  • Added cookies consent, typical modern practice

  • Added social render links, which will make posting links to the docs look more professional

  • Fixed apply_oe docs

    • This was caused by the \b in the docstrings which were needed by Click to actually render the docstring reasonably in the terminal. I worked it around such that the custom Click class will insert these appropriately. This maintains nice terminal docs as well as proper website parsed docs.
      • This is an opt-in feature. As far as I'm aware, only apply_oe used \b formatting, so right now it only applies to that. For other functions, follow the implementation seen at the bottom of apply_oe.py with __doc_source__
  • Snuck in isofit no longer hiding CLI exceptions by default. Given I've been asked by multiple developers how to debug a CLI problem, I think it's best to just allow them to bubble instead. Isoplots ModuleNotFoundError are still hidden and only shown via the --debug flag, but that's the only purpose of the flag now

Note: The gh-pages will need to be deleted before merging this so that mike builds the docs in a different structure

Comment thread pyproject.toml
@pgbrodrick

Copy link
Copy Markdown
Collaborator

Looking good - these changes all seem like solid improvements! Open minor question about dependencies.

@jammont jammont marked this pull request as ready for review February 12, 2026 19:06
@pgbrodrick pgbrodrick merged commit 3c69e1e into isofit:dev Feb 12, 2026
5 of 23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants