Enable ReadTheDocs on v3

[Sayam753]

Preview - https://pymc3-fork.readthedocs.io/en/v3_rtd_docs/

This PR

• Adds a .readthedocs.yml file to build/deploy v3.11.3 docs on ReadTheDocs. The docs will follow the same theme as docs.pymc.io
• Updates the pymc-examples submodule

TODOs

• documentation previews for PRs
  • At PyMC3 RTD portal, we just need to turn on Admin -> Advanced settings -> Build pull requests for this project. And then hit Save (@twiecki helped here :) )
  • A preview of how RTD builds documentation for PRs
    • PR RTD pull request docs check Sayam753/pymc3#1
    • Docs generated https://pymc3-fork--1.org.readthedocs.build/en/1/
• Mention in release notes
• Add link to installation guides on landing page

Questions -

• Should we pin pymc-examples submodule to a specific commit for building v3.11.3 docs?
• In the preview, the Tutorials and Examples pages are empty. Did I miss something while building docs?
  • The contents show up by manually creating the static directories before gallery extension is used
• I created a wiki page here on how to generate documentation for v3. What would be better - Linking this wiki page in PyMC3 documentation or having the instructions inside the documentation itself?

[twiecki]

Thanks! Why do we need RTD if we already have a site?

[Sayam753]

The plan is to switch the deployment to ReadTheDocs from GitHub pages.

Majorly RTD will help in hosting multi versioned docs. Because after v4 release, v3.11.3 docs still need to be present. That's what @OriolAbril's ideas are.

[michaelosthege]

great work!
looking forward to fresh docs.

On the landing page we should probably link to the installation guite wikis. I just tested the conda forge command on Windows and it's not working as expected.

[Sayam753]

On the landing page we should probably link to the installation guite wikis. I just tested the conda forge command on Windows and it's not working as expected.

Definitely yes. Once I get the basic structure ready, we can quickly iterate to add/change stuff.

I have a question though, can the tests be disabled though for some time being for this branch? I am simply changing docs and feeling an overkill that GitHub Actions are running the entire test suite each time.

[michaelosthege]

@Sayam753 you can insert this on the relevant job definitions:

jobs:
  ubuntu:
    if: false

Or alternatively comment out

on:
  #pull_request:
  push:
    branches: [main]

[Sayam753]

I just changed the installation instructions and here's how they look like - https://pymc3-fork.readthedocs.io/en/v3_rtd_docs/

[Sayam753]

The PR is ready to review.

There are a few simple questions remaining in the issue description. Definitely worth discussing.
But they are not a blocker for this PR.

[michaelosthege]

Looks good! The links in the In-Depth Guides section are broken, but I guess that's known?

If we merge his, it won't affect http://docs.pymc.io until we redirect the DNS registration, right?
Because in that case I'd say we should merge so we can iterate faster.

Also it will need to be cherry-picked onto main, right?

[michaelosthege]

Should we pin pymc-examples submodule to a specific commit for building v3.11.3 docs?

I guess so? @OriolAbril maybe via date-based releases?

I created a wiki page here on how to generate documentation for v3. What would be better - Linking this wiki page in PyMC3 documentation or having the instructions inside the documentation itself?

Those instructions are essentially just the standard ones for Sphinx-based doc setups, right?
How about a README.md in the /docs/ directory?

[Sayam753]

Those instructions are essentially just the standard ones for Sphinx-based doc setups, right?

Yes. I just need a place to mention the last step of rendering docs. This is an also attempt at resolving #4619

Furthermore, the instructions will get PyMC specific in case we need to pin pymc-examples to a specific commit for v3.

How about a README.md in the /docs/ directory?

I dont get it. Do you mean inside /docs/source/? because everything that needs to be in hosted documentation, has to be inside /docs/source

[michaelosthege]

I dont get it. Do you mean inside /docs/source/? because everything that needs to be in hosted documentation, has to be inside /docs/source

Just a plain /docs/README.md file in the repository. Not even including it in the hosted documentation.
GitHub renders README.md files also for subdirectories.

[OriolAbril]

I want to play around doing similar things for the main branch. It is one option, yes. But I am not sure 100% sure if this will work (because the theme is entirely different at main)

RTD should have no problems with different versions having multiple themes, see xarray's docs for example: http://xarray.pydata.org/en/stable/ and http://xarray.pydata.org/en/v0.17.0/ have different themes but rtd allows changing between them.

I guess so? @OriolAbril maybe via date-based releases?

Not yet, we have not started using myst yet on pymc-examples so it would be best to build using the latest commit so all notebooks and updates are included. For v4 I think we landed on building examples and docs independently so that would not be an issue.

I created a wiki page here on how to generate documentation for v3. What would be better - Linking this wiki page in PyMC3 documentation or having the instructions inside the documentation itself?

I am strongly opinionated on that being part of the development guide eventually, but to get started a wiki or non-rendered readme are fine.

[Sayam753]

Not yet, we have not started using myst yet on pymc-examples so it would be best to build using the latest commit so all notebooks and updates are included. For v4 I think we landed on building examples and docs independently so that would not be an issue.

I think we will be iterating on development of documentation as things get clear.

I am strongly opinionated on that being part of the development guide eventually, but to get started a wiki or non-rendered readme are fine.

I was about to add a README.md file in /docs/ as suggested by @michaelosthege . But yeah lets keep it a wiki until we have both v3/v4 docs enabled and later decide on where to add/merge it.