New Brightway website technical plan

[cmutel]

Summary

The Brightway website needs a content refresh, and it would be nice to have a single, consistent set of technical principles. We currently use a custom homepage (brightway.dev), with documentation as a combination of ReStructured Text and Jupyter notebooks processed by Sphinx in the brightway2 repo.

Pros and cons of the current implementation

Pros

• ReST allows linking and quoting from docstrings in existing code
• Mixing text and notebooks allows (at least in theory) for
• Linking within ReST text (i.e. to other places in the manual) is relatively easy
• Sphinx builds a search index
• ReST is much easier to text edit than notebooks

Cons

• Is not linked to RTFD, so I have to manually compile the ReST to html to upload to my Vultr server.
• Notebooks are not dynamic via e.g. MyBinder, so newcomers have to install BW, download the notebook, etc.
• Notebooks often use proprietary databases for example data. Important especially for beginner-oriented notebooks.
• Homepage is totally different style and URL from documentation
• Linking from ReST to Notebooks is awkward and/or manual

Prize Amount

150 € or CHF

Output

A plan and implemented technical demonstration of how we can advance the documentation to the "next generation".

This next generation should have some of the following (probably not all are possible):

• API docs are separate from usage examples. Is there a clear boundary between these categories? Maybe we can get inspiration from other Python libraries?
• Using a service like MyBinder, it should be possible to run most of the documentation with example code
• If notebooks are used, a solution for nicely tracking notebooks in git should be proposed and validated
• Linking across notebooks - is this possible or reasonable?
• Technical standards for notebook extensions, if any, including installation environments
• Technical standards for the environment used to build the documentation
• Evaluation of Sphinx, Asciidoc, and possibly other alternatives. Justification for the proposed choice.
• Hosting documentation. Currently at two different sites on a virtual server which requires manual uploading. Would be nice to have the documentation also be the homepage, and update automatically.
• Automatic checking for broken links in documentation.
• Automatic checking for broken code in documentation and usage examples.

Verification

Verification done by @cmutel and one other member of DdS.

[cmutel]

Prize amount is being raised to 150 €/CHF.

[tngTUDOR]

I see a trend in documentation sites that I personally like:

• https://docs.cupy.dev/en/stable/overview.html
• https://developer.mozilla.org/en-US/docs/Web/JavaScript
• https://pip.pypa.io/en/stable/reference/build-system/

3 column organization with actual contents in the middle, and left and right columns for "other topics" or "this topic contents" more or less.

[cmutel]

Due to a lack of interest, closing this issue to break it up into smaller, more digestible chunks.