Switch site to Docusaurus #44
Conversation
- Remove Sphinx stuff
- Prepare formal schema by starting a `schema/` directory with some
rough sketches
- Setup Docusaurus within `web/` directory:
- Initialize Docusaurus and remove all the default stuff
(logos, blog, etc.)
- Establish `docs/` subdirectory for human-readable content about
ethdebug, our efforts, etc.
- Establish `spec/` subdirectory for direct specification materials,
using Docusaurus's mechanism for keeping two "docs" directories.
- Author basic homepage so ethdebug has a proper home on the web
- Define initial version of function for loading schemas from root
`schema/` directory, and reference this schema in the `spec/`
subdirectory.
- Extend theme to provide access to FontAwesome for icons
- Extend theme to include "external link" badge on external links in
Markdown files
- Include a temporary logo generated by ChatGPT
- Override default colors with temporary colorscheme suggested by ChatGPT
- Update GitHub Actions workflows for new toolchain
|
Hi @gnidan, I have reviewed the PR locally and it looks good! The link to specification is name differently in the header and footer ( Specification v/s Specification overview) do you think we should name them the same for the sake of consistency? |
Hm, there's probably a way to avoid this confusion. What you're looking at is the Specification section, which has the "Specification overview" as its landing page. I'm imagining this kind of site map:
We'll probably want to add another main section, like "Community" or "About", since maybe the homepage isn't the best place for meeting schedules and other things... perhaps that is where meeting minutes could live in the future. Anyway, does this make sense? tl;dr maybe: We need to build a spec; we also need to document the spec. Those are two separate parts of the site and both will have lots of info. We should organize that info and provide overviews/landing pages for the different sections. |
|
Yep. That makes so much sense! |
|
I fixed few minor typos in the docs. Should I PR into this branch? or wait till this gets merged? |
I just noticed #45. I'll review that today. Thank you! |
|
No one in Matrix.chat objected broadly, so I'm marking this as ready for review. Please provide any feedback you may have! |
|
Merging this and #45 to reduce the tree of branches targeting this PR. |
As discussed in the 2023-11-29 biweekly call, this PR prepares for a formal-schema-first approach by switching from Sphinx to Docusaurus.
Based on my research, Docusaurus appears to be the most mature documentation site generator that supports JSON Schema draft 2020-12 (sphinx-jsonschema only supports draft 4, which is now ten years old!). I remember reading that draft 2020-12 should be "close to stable", so I think it makes sense for us to use that as our JSON Schema version moving forward.
If you'd like to preview these changes, I quickly set up a Fleek project, which provides a service to build+deploy GH repos as static IPFS sites behind their CDN. This service might be nice for us to use for PR/branch previews, since they provide that feature out of the box. (This PR just keeps the existing GHA deployment to gh-pages, though... I don't think we want to switch entirely to Fleek? At least now in this PR.)
For a breakdown of the various moving parts, this PR includes changes that:
schemas/directory with some rough sketches in YAMLweb/directory:docs/subdirectory for human-readable content about ethdebug, our efforts, etc.spec/subdirectory for direct specification materials, using Docusaurus's mechanism for keeping two "docs" directories.schema/directory, and reference this schema in thespec/subdirectory.