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.
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.
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.
|
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-builderthat adds better Docusaurus support (e.g. admonitions) to render the Sphinx docs to markdown documents./docsby a special script that also handles some minor postprocessing (addingsidebar_position, rewriting some URLs, etc)./docsas 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.htmlinstead 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-builderfork 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.