Add proposal for new Sphinx and RTD tutorials

[astrojuanlu]

After reflecting a lot on Daniele Procida's thoughts on documentation, gathering information from several existing Sphinx tutorials and drawing inspiration from documentation of other projects, I tried to conceive the tutorial as a syllabus, a learning path that we propose to the reader, that should be ordered and structured in a meaningful way. In that vein, it starts with the creation of a small Python project, setting up a virtual environment, and using git. I left this last bit as optional, but I actually think it should be used all throughout the tutorial. Would love to know your thoughts on that.

We intend these new guides to be useful for the broad Python community, without forgetting about scientific users and their needs. In particular, I'd like to write most of the material in Markdown rather than reStructuredText, and pay special attention to the integration of Jupyter notebooks.

I devoted more effort to break out the first sections into smaller steps up front, so the intent and the overall philosophy are more clear to those reviewing, and left the final sections more open ended. Besides, I also proposed several topics we could cover as How-to guides, especially for people that already know the basics of Sphinx but want to address particular problems.

Rendered version: https://docs--8106.org.readthedocs.build/en/8106/development/design/new-sphinx-guides.html

[ericholscher]

This is a great start, but I think we definitely need more thought around what we want to focus on and audience of this content. I think we definitely want to think through where external resources can be used here, and what we want to "own" in terms of our content. We will be responsible for keeping this information up to date, so we definitely want to keep the scope smaller to start, and link out to externally maintained tutorials where possible.

I think we also need to think about where this content will live. Are we doing to add it to the RTD docs? Sphinx docs? Both? Neither? That will help scope what we want to handle.

I think the biggest goals for me are:

• Building a tutorial for Sphinx, which will likely live in their docs
  • Introducing people to all the various Sphinx features in order of value/complexity, in a narrative format
• Building a tutorial for RTD, which will live in our docs
  • This is similar to our guides, but in an overarching narrative, perhaps continued from the Sphinx tutorial?

But we need to discuss a bit more in depth the overall goals of this work I think. I don't have a full understanding of how it should all fit together, but it's definitely something to think through.

[astrojuanlu]

About

I think we definitely want to think through where external resources can be used here, and what we want to "own" in terms of our content. We will be responsible for keeping this information up to date, so we definitely want to keep the scope smaller to start, and link out to externally maintained tutorials where possible.

This applies mainly to virtual environments and version control. We agreed to:

• Leave version control out (too confusing, even though it's a recommended good practice - and git in particular is known to be tough for beginners)
• Keep virtual environments as part of the workflow, but don't delve into details and send users to external resources instead

[astrojuanlu]

About the mismatch of the markup we want to use (Markdown/MyST) and sphinx-quickstart producing a index.rst file by default:

Proposing a flag to sphinx-quickstart to produce a index.myst file instead might be contentious, in that it would probably require Sphinx to depend on MyST-Parser. Instead of going that way, we agreed to use a cookiecutter. More details to follow in the document.

[astrojuanlu]

• Addressed most of the comments (replied inline to those)
• Left unresolved the conversation about PDFs (I still think they are important and useful)
• Missing: proposal for Read the Docs tutorial

[ericholscher]

This is feeling a lot closer. Excited to bring it up with other folks in the community, so we should discuss that plan for that tomorrow. 👍

[astrojuanlu]

The Sphinx part is essentially there. I uploaded the RTD tutorial. In the same spirit, I added more detail to the initial chapters and left the final ones more open (also, because I still have to figure out many things, like translations!)

[humitos]

because I still have to figure out many things, like translations

Let me know when you are ready to jump into this, and I can share what I know from python-docs-es.

[ericholscher]

Looks great. I think the RTD tutorial is missing a couple things:

• Show simple edits building docs via webhook (early in the process)
• Alternative outputs (Look how simple PDF is on RTD!)

[ericholscher]

👍 -- Automation rules is probably an advanded/appendix topic, unless we have a simple, obvious example for it.

[astrojuanlu]

I do have a simple use case in mind - automating something I've been doing manually in poliastro for years 😄 but I'd also want to think through @humitos ideas here readthedocs/blog#74

[ericholscher]

• https://numpy.org/numpy-tutorials/
• https://gitpod.io
• Guide for using Jinja & Sphinx to fix this: https://raw.githubusercontent.com/divio/divio-cloud-docs/main/how-to/deploy-template.rst (base template & extends vs includes). Initial content here: https://www.ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/#generating-docs-from-data

Binder for tutorial environments, gitpod for a "devy" type environment.

[astrojuanlu]

Comments from sphinx-doc/sphinx#9165 (will keep updating):

• More detailed treatment of toctree?
• Mention of intersphinx
• Contentious choice of Markdown/MyST (to be discussed separately?)
• ...

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ericholscher]

We should probably just merge this, I think?

[ericholscher]

This is in progress.

[astrojuanlu]

@ericholscher What about adding a note at the top saying "this is in progress, see sphinx-doc/sphinx#9165 and linked pull requests" and merging it then?

[ericholscher]

@astrojuanlu Works for me 👍

[astrojuanlu]

Added, and merging 👍🏽