Skip to content

refactor(docs): port entire documentation from mkdocs to hugo #1899

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

Open
wants to merge 10 commits into
base: main
Choose a base branch
from

Conversation

felix314159
Copy link
Collaborator

🗒️ Description

To make maintaining docs easier and faster I think we should port them to hugo. This PR would be followed up with another PR to cut the then unneeded dependencies which makes future uv lock upgrades much less painful:

  • cairosvg
  • mike
  • mkdocs
  • mkdocs-click
  • mkdocs-gen-files
  • mkdocs-git-authors-plugin
  • mkdocs-glightbox
  • mkdocs-literate-nav
  • mkdocs-material
  • mkdocs-material-extensions
  • mkdocstrings
  • mkdocstrings-python
  • pillow
  • (potentially a few more)

What works already

  • Linking between files (e.g. one md to another md, one md to a specific section of another md)
  • Embedding images
  • Tables that look like before
  • Colored boxes (so-called callout boxes)
  • Selectable tabs (e.g. user can choose OS in tab and the shown code varies depending on chosen tab)
    I did most of the porting already

Note: I have not yet fixed all instances of the above things we can do, but I am working on it as we speak. It is a fairly fast process as we merely have to replace old syntax with new syntax.

What still needs to be fixed

  • Navigation (we either vibecode the navigation css or ask someone who knows css, it should be straightforward)
  • Search function (haven't looked into this)
  • Discussion on whether we need old versions of docs to be selectable (who uses this) and whether we need to have auto-generated testcases

How to see the current status of ported docs

Download latest hugo binary, cherry-pick this PR, navigate into docs folder and run hugo server

🔗 Related Issues or PRs

N/A.

✅ Checklist

  • All: Ran fast tox checks to avoid unnecessary CI fails, see also Code Standards and Enabling Pre-commit Checks:
    uvx --with=tox-uv tox -e lint,typecheck,spellcheck,markdownlint
  • All: PR title adheres to the repo standard - it will be used as the squash commit message and should start type(scope):.
  • All: Considered adding an entry to CHANGELOG.md.
  • All: Considered updating the online docs in the ./docs/ directory.
  • All: Set appropriate labels for the changes (only maintainers can apply labels).
  • Tests: Ran mkdocs serve locally and verified the auto-generated docs for new tests in the Test Case Reference are correctly formatted.
  • Tests: For PRs implementing a missed test case, update the post-mortem document to add an entry the list.
  • Ported Tests: All converted JSON/YML tests from ethereum/tests or tests/static have been assigned @ported_from marker.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant