Move website from Docusaurus to Sphinx
jbesomi opened this issue · 5 comments
Motivation
Initially, docusaurus.io has been chosen as a tool to visualize Texture's documentation on the website.
Docusaurus is great for two reasons: it's very beautiful and it's super easy to use as users need to write simple markdown files.
Docusaurus's main drawback is that it does not support natively Sphinx, the python documentation generator used to create documentation from the docstrings.
As of now, the API documentation is generated through Sphinx and a python function (to_docusaurs.py) is used to map Sphinx's html files to Docusaurus's markdown files.
This solution, even if it works, is not practical and that's why we should move texthero to Sphinx.
Implementation
Goal: move Texthero's website from Docusaurus to Sphinx.
Sphinx theme: pydata-sphinx-theme as it is very elegant and it resembles the actual website design.
The design should be adapted (not really a complex task) to match almost perfectly the current Texthero's design. This basically means change some CSS to match Texthero's colors and adapt the menu bar.
There is some extra work to do to create the homepage. The homepage will be probably hardcoded in an Html files, without using React (Javascript) as it's the case now with Docusaurus.
Extra
Once ported on Sphinx, it will be possible to add new functionalities to the API's page. Some of the most important are:
- Add the 'source' button to every function for easy lookup of the code
- Add Sphinx internationalization, i.e multilingual support. I have no idea yet how this will/should work, any help is much welcomed!
- New ideas
Collaboration
If you've read this far; wow, congrats! If you are interested in helping with this (very important!) task just leave a comment, or, if you prefer, contact me directly: jonathanbesomi__AT__gmail.com
@jbesomi I see this issue being referenced multiple times so I'm guessing this is one of the priority items. Can I help with this or is this taken up by someone already?
I am a beginner on Sphinx, but with some pointers, I can probably work on the task.
Hey @avinashbhat, sorry for my late reply.
Absolutely, this is quite first priority. And no, nobody already took it. Do you want to start and see how it goes? Is the task clear?
I got here via Google. I was expecting to see the opposite: "Move website from sphinx to Docusaurus". I'm surprised.
I'm a python programmer that uses sphinx-doc on 10+ websites (including API generation). I prefer markdown.
One area where Sphinx is strong is API documentation. I haven't been able to find a suitable alternative.
https://tmuxp.git-pull.com - example of a sphinx site, and recently a docusaurus v2 website: https://social-embed.git-pull.com
I loved building with docusaurus. I dread having to open up sphinx. Sphinx used to be the "go to" choice for customization. With gatsby/next/docusaurus and SSR, the case for sphinx-doc is weaker. Still - none of my python projects use it :/
I'd like to drop a link, while I haven't tried yet: https://pydoc-markdown.readthedocs.io/en/latest/docs/renderers/docusaurus-v2/
Also arrived here from Google and also surprised 🙃
I'm a python programmer that uses sphinx-doc on 10+ websites (including API generation). I prefer markdown.
You can write Markdown in Sphinx: https://myst-parser.readthedocs.io/
I'm also switching from sphinx to docusaurus. pydoc-markdown + docusaurus renderer is exactly what I was searching for. Thanks, @tony.