A proposal to improve our documentation workflow

[javabster]

Our current documentation workflow is not the most efficient and gives rise to many inconsistencies across our many Qiskit repos. This rfc aims to start conversation about how we could improve this process

[1ucian0]

If you divorce the actual static content building from the sphinx build itself you basically make it impossible for people writing new documentation to know exactly how things will look without the full web dev pipeline.

The developer writing documentation should focus on the content of article (the main content body) and not the toc, menus, footers, and the like. I agree than provider a way for developers to render that as it will be published is necessary.

The current approach of static pages makes it impossible to integrate different built instances. Take the example of versioning. Once you clicked in a previous version (say you are in 0.39 and you clicked in 0.38) there is not way back (in this case, to 0.39)

https://user-images.githubusercontent.com/766693/199343589-3ee2ffe8-786c-4310-90ac-f9d23c48b884.mov

With the current approach, there is no solution to this problem, because once pages are created, they cannot be changed. The PyTorch approach was https://pytorch.org/torchx/versions.html, but even there it is not consistent along components (https://pytorch.org/torchrec/ has no version selector, or shows the version at all). Similarly, also in PyTorch there is no consistency on the top menu.

https://user-images.githubusercontent.com/766693/199345874-dee4763f-8872-41ec-b3b5-44e7c38efbaf.mov

Hopefully this shows that we need a way to disentangle content from layout.

[mtreinish]

You're conflating a few different things which aren't really related to the point I was making before. Static content hosting is a requirement for how we host the website and there is no option for an interactive dynamic web application to run code server side. This isn't going to change and is also not what this proposal is about (at least as I read it).

The limitations you're pointing at aren't inherent to static content, you can build a solution around having shared version links fairly easily using a reference to a shared file in a consistent relative path very easily. The specific issue about versions tables not being updated for past releases that you're pointing out there is because we evaluate the versions at build time, which was a specific decision in Qiskit/qiskit#1261. We discussed how to do this when we added the stable version documentation originally and I laid out a rough sketch of how to do it (you can see the start of work on this earlier in Qiskit/qiskit#574 but we never finished it as it wasn't a priority), but nobody had the bandwidth to implement it at the time and we settled on doing the faster to implement solution which got us most of what we wanted.

The problem with saying the content writer/developer shouldn't have to worry about the layout is that they're actually far more coupled than it might first appear given how sphinx works. The exact method the docstrings get rendered together is by filling out templates with the content from the actual documentation and what the exact layout looks like. This doesn't actually change in this proposal either it just changes the mechanism by which this happens. For example the contents of the document determine what gets populated in table of contents which end up in side bars, etc. Similarly theme decisions can impact how things get rendered and can inform decisions around how you choose to format elements in the documentation. To do a good job writing documentation you need to be able to build the final compiled output locally, and adding an entire parallel JS build framework for doing that is pretty much a non-starter from my PoV; people already have enough issues with building docs to add the complexity on top of it.

[Eric-Arellano]

We've decided to not pursue this Chimera approach for now. We are sticking to using only Sphinx, and migrating to Furo so that the code is more maintainable and we have better front end like being more responsive on mobile.

@javabster can you please close this?