Documentation rewriting and reorganizing

[OriolAbril]

I have some ideas inspired by numpy and pandas websites, but they require a serious rewrite of the docs which will probably take a long time unless someone got paid to do it via google season of docs (next one is one year from now so still a long time thouth) or so.

Currently, the whole website at https://docs.pymc.io/ is sphinx generated, however, sphinx has noting to do with the home page or books+videos tabs, and some others like about and tutorials/examples can easily be made sphinx independent.

I think it would be a good idea to follow numpy's and pandas' steps and create a standalone website that then links to the sphinx generated documentation and the notebook gallery with tutorials.

The "home" website would have the learn page with books, videos, link to the resources page, links to pymcon talks and tutorials; how to support pymc info, how to contribute, members of the project,

What would be left in sphinx-generated-docs still has to be decided, but as a beggining point: getting started guide with installation, module level descriptions (which I am not even sure exist), api reference and developer guide. Ideally, this weebsite would be the one to have multiple versions available for multiple pymc releases.

Notebooks could then be moved to its own repository with its own zenodo. For this there are several options on how to serve/convert to website, the two extremes being probably the current examples page of the docs and having a table with links to completely external repos with its own html version/using nbviewer with may possibilities in between such as Stan's case studies.

I think we can use this issue to brainstorm and discuss how should docs and pymc website look and then start working on pymc-devs.github.io repository as the home website, create the notebooks repo...

Possibly useful references: https://thegooddocsproject.dev/ and https://github.com/numfocus/doc-standards

[michaelosthege]

A notebook repo with Zenodo-DOI sounds very good. In terms of rendering, this repo could even contain some kind of index file from which the main docs site could just render a table of contents/links!

I think having a very small set of agnostic notebooks (API quickstart) that just show API things in the main repo is also favorable, but I don't know how much trouble it adds for doc-building.

[OriolAbril]

I think having a very small set of agnostic notebooks (API quickstart) that just show API things in the main repo is also favorable, but I don't know how much trouble it adds for doc-building.

It should be no problem, and if the notebooks left are fast enough to run, nbsphinx can be used to automatically run them when building docs. The option is now turned off, but could eventually be on for docs and off for examples

[fonnesbeck]

Are there other alternatives? We should probably do an exhaustive search and consider the options fully if we are going to commit the time and resources to moving the docs.

[OriolAbril]

Yes, I wanted to use the issue to discuss alternatives and eventually decide always taking into account the effort each alternative will require

[AlexAndorra]

I don't have a lot of expertise on this, but I trust Oriol's and do think our docs could use a good revamp!
I like this idea of creating a home website that links to a notebook gallery with tutorials on the one hand, and sphinx-generated docs that users can display for several different versions of PyMC on the other hand 👌
GSoD definitely sounds like a good option to get this done, but maybe we could complement this to start early, depending on how our fundraising operations go?

[ColCarroll]

The notebooks and example gallery are sphinx independent-ish. I hacked on the gallery generator which was from mpl3d -> seaborn -> us.

It is pretty brittle, but also ~readable python, so we can fix that.

I sort of like having everything in one repo! The zenodo-doi sounds cool, but I worry about coordination and discoverability.

[fonnesbeck]

I like having the docs in the same repo, but it might be nice to spin off the notebooks as they continue to grow.

[aloctavodia]

Do you mean a zenodo per notebook? The idea is to have citable notebooks? Isn't enough to cite the webpage? Or getting a single doi for the entire webpage?

[michaelosthege]

Do you mean a zenodo per notebook? The idea is to have citable notebooks? Isn't enough to cite the webpage? Or getting a single doi for the entire webpage?

In my opinion a single DOI for the notebooks is enough. But it's important to make it a Zenodo-DOI, because otherwise the notebook contributors aren't credited.

[twiecki]

I would prefer we keep the various issues separate and also attack them separately.

• It seems we all agree on a Zenodo-DOI being a good idea which is also easy to do so we should go ahead on that.
• The docs are already independent as @ColCarroll points out. What more do we need?
• I also like the NBs in the repo, but I'm also fine moving them out. Do they make the repo too slow? I think we fixed the pypi issue (CC @michaelosthege), right? Rather I think we can probably do a lot of clean-up work there and remove those that aren't high-quality.

[fonnesbeck]

In preparation for the Season of Docs proposal, I've got a Wiki page here for ideas related to changes we want to see in the docs. Feel free to add and edit over the next week or so.

[ricardoV94]

@OriolAbril should we close this one? I think the discussion on docs has moved elsewhere?

[OriolAbril]

I think the discussion on docs has moved elsewhere?

Yes, we are now tracking all this on clickup. I am not sure about closing or not though. @martinacantaro may have an opinion on this.