WWW: Select a dev-friendly tool to publish the web site

[pombredanne]

We use rst and sphinx for the docs and this enables a distributed workflow. We need to do a lot of work to improve the docs and unify it across all different projects/repos, enable intersphinx and get better readmes #15

And we should also adopt a similar approach for aboutcode.org .... sphinx my not be the best for this though, so here are some tools:

• docusaurus
• https://getpelican.com/
• lektor
• https://github.com/gohugoio/hugo/

To me the important aspect is that content should be based on plain text files and stored in git. Search and comments are nice but not really critical.

(Note: we considered using some of these in the past.)

[pombredanne]

In a chat with @tdruez he simply reminded us that could also consider using Sphinx for the site too.
See for instance:

• https://sunpy.org/
• https://sphinx-themes.org/
• https://pydata-sphinx-theme.readthedocs.io/
• https://sphinxdocs.ansys.com/
• https://docs.pytorch.org/docs/main/torch.html
• https://docs.pytorch.org/tutorials/
• https://bashtage.github.io/sphinx-material/

@adaaaam @Thatwriterjon @tsteenbe FYI

[AyanSinhaMahapatra]

Static site generators seems to work quite nicely, jekyll/pelican are quite nice and in python, but are kind of basic looking, kind of like sphinx sites with nicer themes. The sphinx themes above are also not too bad.
But even something like this is better than having aboutcode.org build by wordpress, as the code stays in open, easier to edit/write blogs etc.

But something more with a bit of JS/CSS would be even better looking IMHO, for example see this hugo theme with tailwind css: https://github.com/nusserstudios/tailbliss, demo at https://tailbliss.netlify.app/
This is nice and looks very much like our website, with all the nice UI elements. Something like this could be great, if generated entirely statically and if the load latencies are not too high. Templating is slightly more involved than plain .rst/.md writing, but once set up, extremely easy to modify.

I used something like this for my personal website too when I made it quite some years back around ~2020 (before GSoC/GSoD):

• https://github.com/AyanSinhaMahapatra/AyanSinhaMahapatra.github.io/ I used jekyll for the blog and some themes with JS/templating for landing/other pages
• https://ayansinha.dev/ayan/ and https://ayansinha.dev/blog/ these are quite old and not maintained much, but you get the idea that this is easy to maintain. These days the themes are even better/easier to maintain

Hugo seems to have a lot more themes and more popular generally than the themes of pelican

The components/themes seems mostly open-source too, at first glance, but we can always verify before using.

[mjherzog]

We used Pelican in the recent past for aboutcode.org and it was underwhelming. We also looked pretty closely at Lektor and decided against using it.
And Lektor requires a plugin for RST (uses its won .lr format as primary).

[pombredanne]

The best contenders at this stage would be:

• Sphinx, using the Markdown plugin (written in Python)
• Mkdocs, potentially with the Mkdocs for material, if we switch to markdown (written in Python)
• Docusaurus if we switch to markdown (written in TS and React)

[mjherzog]

@pombredanne A fundamental question at this point in time is the relationship between the aboutcode.org website and the project-level documentation. My sense is the function of the website is to provide an entry point for AboutCode as a whole and information about how the projects fit together. It does not seem practical (or desirable?) to try to move all of our documentation to a single website.
The urgent item is to replace the Wordpress-based website with one that makes it easier for a wide range of contributors to participate. We can work in parallel to improve the project-level documentation in the existing rST/Sphinx/RTD framework.
Based on my research into MKdocs vs Docusaurus it seems that a JS/TS/some-framework platform like Docusaurus provides more options for an engaging general audience website than the Python-based frameworks (including Mkdocs).
We need to use the right tool for the job.

[pombredanne]

@mjherzog let's go for it then: Docusaurus it is!