-
-
Notifications
You must be signed in to change notification settings - Fork 274
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
Render Sphinx /docs
in docusaurus
#2077
Conversation
✅ Deploy Preview for conda-forge-previews ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
yaml = YAML(typ="safe") | ||
yaml.default_flow_style = False | ||
|
||
SIDEBAR_ORDERING = [ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If we change the website's high-level structure, does that mean this list will need to change too? If yes, we should add a comment and maybe have some sort of CI check.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good catch! Added a check to raise if the document is not found in this list. Hopefully, if we start changing sphinx/
stuff, is to bring it over to Docusaurus, so "this should not happen" but better be safe than sorry.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM from me but I left a few comments.
Well I tried to fix the core and emeritus member lists @jaimergp but I think I am missing something important about how sphinx is working now or I got the relative path wrong. |
Let me take a look, you mean the governance.rst substitution, right? |
Ok, the early return branch made us skip that part because the rendered is not HTML anymore, but Markdown. I adjusted a couple things and also added the CFEP substitution there because it's cleaner (otherwise you might risk accidentally committing the rendered version, like it happened two days ago :D). |
Awesome. This last thing was the only comment on slack. I'd say lgtm and let's merge this. Any other issues can be fixed later. |
Yes, I can take a look on the search bar too. Hopefully it starts working once we merge. I don't see any difference with conda.org's setup. |
PR Checklist:
sphinx-markdown-builder
that adds better Docusaurus support (e.g. admonitions) to render the Sphinx docs to markdown documents./docs
by a special script that also handles some minor postprocessing (addingsidebar_position
, rewriting some URLs, etc)./docs
as if they were written by hand and publish the site./path/thing/
are preferred to file names like/path/thing.html
. Our Sphinx site also had strange00_intro.html
instead ofindex.html
. To that effect, we have added redirects from/path/to/thing.html -> /path/to/thing/
and/path/00_intro.html -> /path/
.lunr
(local search, JS plugin, not as powerful).Notes for reviewers:
sphinx-markdown-builder
fork situation is a bit fragile. We can try to upstream things but: (1) some things are Docusaurus specific and might need options; (2) this is supposed to be temporary to some degree, because ideally we would end up writing everything in native Docusaurus 🤞. If (2) doesn't happen, then yes, upstreaming is even more important.