Docs: Read the Docs for Science - first version landing page in user documentation (#9460)

* Add science chapter

* WIP: Updates to Read the Docs for Science, left a few TODOs around

* Use sphinx-design :dropdown: instead of term list

* Apply suggestions from code review @ericholscher

Co-authored-by: Eric Holscher <[email protected]>

* Adds sphinx-design to docs.in and run pip-compile

* WIP: cards in a grid with logos of cool projects

* WIP: Expanding features and adding video

* Ignore dropdown for rst-check

* Add some missing directives and roles for rstcheck

* Added 3 example projects to make the section of logos look pretty

* Add a screenshot and a video

* Ignore further directives for button-*

* More refinements in text and rstcheck

* Adds a screenshot (to be improved) with the Edit on Github button

* Oh *sigh* merge conflict artifact

* A few more refinements of structure and text

* Replace button with text link, Expand the SEO feature to generic Search and Analytics and add more description

* Center the video

* Crop screenshot re: https://github.com/readthedocs/readthedocs.org/pull/9460/files/14c5770e3645bf8eb1a64d295418163342051dc9#diff-27b7d89454610338aba49b760a3126183ee6923631b348f450e3d856da9f3eed

* Reduce jupyter logo file size

* Apply @agjohnson's code review suggestions

Co-authored-by: Anthony <[email protected]>

* Remove assumption about reader confusion in language

* Update some of the exit-links with a "»" to indicate that this is a "next step" thing

* Add note about this page and update video link

Co-authored-by: Eric Holscher <[email protected]>
Co-authored-by: Anthony <[email protected]>

Author: 3 people

docs/.rstcheck.cfg

@@ -1,6 +1,6 @@
 [rstcheck]
-ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post,http:put,http:delete
-ignore_roles=djangosetting,setting,featureflags,buildpyversions,external+rtd:doc,external,external+rtd
+ignore_directives=automodule,dropdown,grid,http:get,tabs,tab,prompt,http:patch,http:post,http:put,http:delete,button-ref,button-link
+ignore_roles=djangosetting,setting,featureflags,buildpyversions,external+rtd:doc,external,external+rtd,external+jupyterbook:doc,external+jupyter:doc
 ignore_substitutions=org_brand,com_brand,:smile:,:arrows_counterclockwise:,:heavy_plus_sign:,:tada:,:heart:,:pencil2:
 # This error needs to be ignored for now
 # See: https://github.com/myint/rstcheck/issues/19

docs/conf.py

@@ -34,6 +34,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinxcontrib.httpdomain",
+    "sphinxcontrib.video",
     "djangodocs",
     "doc_extensions",
     "sphinx_tabs.tabs",
@@ -42,6 +43,7 @@
     "hoverxref.extension",
     "sphinx_search.extension",
     "sphinxemoji.sphinxemoji",
+    "sphinx_design",
     "myst_parser",
 ]
 
@@ -89,9 +91,11 @@
     "myst-parser": ("https://myst-parser.readthedocs.io/en/stable/", None),
     "writethedocs": ("https://www.writethedocs.org/", None),
     "jupyterbook": ("https://jupyterbook.org/en/stable/", None),
+    "executablebook": ("https://executablebooks.org/en/latest/", None),
     "rst-to-myst": ("https://rst-to-myst.readthedocs.io/en/stable/", None),
     "rtd": ("https://docs.readthedocs.io/en/stable/", None),
     "rtd-dev": ("https://dev.readthedocs.io/en/latest/", None),
+    "jupyter": ("https://docs.jupyter.org/en/latest/", None),
 }
 # Redundant in Sphinx 5.0
 # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes

docs/user/img/logo_chain_ladder.png

@@ -164,6 +164,7 @@ and how to write successful documentation.
  /guides/authors
  /guides/administrators
  /guides/developers
+ /science
  /examples
 
 Advanced features of Read the Docs

docs/user/img/logo_feature_engine.png

@@ -0,0 +1,161 @@
+Read the Docs for Science
+=========================
+
+.. 2022-08-10
+.. Notes about this section:
+..
+.. This section is intended as a "landing page", meaning that we will allow to
+.. mix messages in a pragmatic way UNTIL a permanent location for this landing
+.. page is found outside of the RTD User Documentation project.
+.. more discussion: https://github.com/readthedocs/readthedocs.org/pull/9460/
+..
+.. The main ways that the page will be improved are:
+.. - Add more focus to documentation perspectives
+.. - Move all descriptions of "benefits", i.e. marketing to a separate location
+.. - Likely stop using the dropdown element
+.. - Continue to function as a "landing" page, but a landing page for
+..   documentation resources for scientific/academic projects.
+
+Documentation and technical writing are broad fields.
+Their tools and practices have grown relevant to most scientific activities.
+This includes building publications, books, educational resources, interactive data science, resources for data journalism and full-scale websites for research projects and courses.
+
+Let's explore the overlap of features for software documentation and academic writing.
+Here's a brief overview of some :doc:`features <features>` that people in science and academic writing love about Read the Docs:
+
+.. dropdown:: 🪄 Easy to use
+    :open:
+
+    Documentation code doesn't have to be written by a programmer. In fact, documentation coding languages are designed and developed so you don't have to be a programmer, and there are many writing aids that makes it easy to abstract from code and focus on content.
+
+    Getting started is also made easy:
+
+      * All new to this? Take the official :external+jupyterbook:doc:`Jupyter Book Tutorial <start/your-first-book>`
+      * Curious for practical code? See :doc:`/examples`
+      * Familiar with Sphinx? See :doc:`/guides/jupyter`
+
+.. dropdown:: 🔋 Batteries included: Graphs, computations, formulas, maps, diagrams and more
+
+    Take full advantage of getting all the richness of :external+jupyter:doc:`Jupyter Notebook <index>` combined with Sphinx and the giant ecosystem of extensions for both of these.
+
+    Here are some examples:
+
+    * Use symbols familiar from math and physics, build advanced proofs. See also: `sphinx-proof <https://sphinx-proof.readthedocs.io/en/latest/syntax.html>`__
+    * Present results with plots, graphs, images and let users interact directly with your datasets and algorithms. See also: `Matplotlib <https://matplotlib.org/stable/tutorials/introductory/usage.html>`__, `Interactive Data Visualizations <https://jupyterbook.org/en/stable/interactive/interactive.html>`__
+    * Graphs, tables etc. are computed when the latest version of your project is built and published as a stand-alone website. All code examples on your website are validated each time you build.
+
+.. dropdown:: 📚 Bibliographies and external links
+
+    Maintain bibliography databases directly as code and have external links automatically verified.
+
+    Using extensions for Sphinx such as the popular `sphinxcontrib-bibtex <https://sphinxcontrib-bibtex.readthedocs.io/>`__ extension, you can maintain your bibliography with Sphinx directly or refer to entries ``.bib`` files, as well as generating entire Bibliography sections from those files.
+
+.. dropdown:: 📜 Modern themes and classic PDF outputs
+
+    .. figure:: /img/screenshot_rtd_downloads.png
+        :align: right
+
+    Use the latest state-of-the-art themes for web and have PDFs and e-book formats automatically generated.
+
+    New themes are improving every day, and when you write documentation based on Jupyter Book and Sphinx, you will separate your contents and semantics from your presentation logic. This way, you can keep up with the latest theme updates or try new themes.
+
+    Another example of the benefits from separating content and presentation logic: Your documentation also transforms into printable books and eBooks.
+
+.. dropdown:: 📐 Widgets, widgets and more widgets
+
+    Design your science project's layout and components with widgets from a rich eco-system of open-source extensions built for many purposes. Special widgets help users display and interact with graphs, maps and more. :external+jupyterbook:doc:`Several <content/components>` `extensions <https://sphinx-gallery.github.io/>`__ are built and invented by the science community.
+
+.. dropdown:: ⚙️ Automatic builds
+
+    Build and publish your project for every change made through Git (GitHub, GitLab, Bitbucket etc). Preview changes via pull requests. Receive notifications when something is wrong. How does this work? Have a look at this video:
+
+    .. video:: https://anti-pattern-sphinx-video-downloader.readthedocs.io/_static/videos/enable-pull-request-builders.mp4
+       :width: 100%
+       :height: 300
+
+.. dropdown:: 💬 Collaboration and community
+
+    .. figure:: /img/screenshot_edit_on_github.png
+        :align: right
+
+    Science and academia have a big kinship with software developers: We ❤️ community. Our solutions and projects become better when we foster inclusivity and active participation. Read the Docs features easy access for readers to suggest changes via your git platform (GitHub, GitLab, Bitbucket etc.). But not just any unqualified feedback. Instead, the *code* and all the tools are available for your community to forge qualified contributions.
+
+    Your readers can become your co-authors!
+
+    Discuss changes via pull request and track all changes in your project's version history.
+
+    Using git does not mean that anyone can go and change your code and your published project. The full ownership and permission handling remains in your hands. Project and organization owners on your git platform govern what is released and who has access to approve and build changes.
+
+.. dropdown:: 🔎 Full search and analytics
+
+    Read the Docs comes with a number of features bundled in that you would have to configure if you were hosting documentation elsewhere.
+
+    Super-fast text search
+        Your documentation is automatically indexed and gets its own search function.
+
+    Traffic statistics
+        Have full access to your traffic data and have quick access to see which of your pages are most popular.
+
+    Search analytics
+        What are people searching for and do they get hits? From each search query in your documentation, we collect a neat little statistic that can help to improve the discoverability and relevance of your documentation.
+
+    SEO - Don't reinvent Search Engine Optimization
+        Use built-in SEO best-practices from Sphinx, its themes and Read the Docs hosting. This can give you a good ranking on search engines as a direct outcome of simply writing and publishing your documentation project.
+
+.. dropdown:: 🌱 Grow your own solutions
+
+    The eco-system is open source and makes it accessible for anyone with Python skills to build their own extensions.
+
+We want science communities to use Read the Docs and to be part of the documentation community 💞
+
+Getting started: Jupyter Book
+-----------------------------
+
+:external+jupyterbook:doc:`Jupyter Book <intro>` on Read the Docs brings you the rich experience of computated `Jupyter <https://jupyter.org/>`__ documents built together with a modern documentation tool. The results are beautiful and automatically deployed websites, built with Sphinx and :doc:`Executable Book <executablebook:index>` + all the extensions available in this ecosystem.
+
+Here are some popular activities that are well-supported by Jupyter Book:
+
+* Publications and books
+* Course and research websites
+* Interactive classroom activities
+* Data science software documentation
+
+
+:doc:`Visit the gallery of solutions built with Jupyter Book » <executablebook:gallery>`
+
+
+Ready to get started?
+"""""""""""""""""""""
+
+.. Note that this is a deliberate repitition of a previous segment. Should it repeat? Maybe not, but for now it's nice to be sure that people see it.
+
+* All new to this? Take the official :external+jupyterbook:doc:`Jupyter Book Tutorial » <start/your-first-book>`
+* Curious for practical code? See the list of :doc:`Example Projects » </examples>`
+* Familiar with Sphinx? Read :doc:`How to use Jupyter notebooks in Sphinx » </guides/jupyter>`
+
+
+Examples and users
+""""""""""""""""""
+
+.. TODO: get the correct link for
+.. :external+jupyter:ref:`the many sub-projects of Jupyter <index.md#sub-project-documentation>`
+
+Read the Docs community for science is already big and keeps growing. The :external+jupyter:doc:`Jupyter Project <index>` itself and `the many sub-projects of Jupyter <https://docs.jupyter.org/en/latest/#sub-project-documentation>`__ are built and published with Read the Docs.
+
+.. grid:: 3
+    :gutter: 2
+    :padding: 0
+
+    .. grid-item-card:: Jupyter Project Documentation
+      :img-top: img/logo_jupyter.png
+      :link: https://docs.jupyter.org/
+
+    .. grid-item-card:: Chainladder - Property and Casualty Loss Reserving in Python
+      :img-top: img/logo_chain_ladder.png
+      :link: https://chainladder-python.readthedocs.io/
+
+    .. grid-item-card:: Feature-engine - A Python library for Feature Engineering and Selection
+      :img-top: img/logo_feature_engine.png
+      :link: https://feature-engine.readthedocs.io/en/latest/
+
+.. Let's put some logos to sign off

docs/user/img/logo_jupyter.png

@@ -6,6 +6,7 @@ Pygments==2.12.0
 sphinx_rtd_theme==1.0.0
 sphinx-tabs==3.3.1
 sphinx-intl==2.0.1
+sphinx-design==0.2.0
 sphinx-multiproject==1.0.0rc1
 readthedocs-sphinx-search==0.1.1
 

docs/user/img/screenshot_edit_on_github.png

@@ -1,4 +1,3 @@
-# pyup: ignore file
 #
 # This file is autogenerated by pip-compile with python 3.10
 # To update, run:
@@ -81,6 +80,8 @@ sphinx==4.5.0
     #   -r docs.in
     #   myst-parser
     #   sphinx-autobuild
+    #   sphinx-design
+    #   sphinx-hoverxref
     #   sphinx-intl
     #   sphinx-prompt
     #   sphinx-rtd-theme
@@ -89,6 +90,8 @@ sphinx==4.5.0
     #   sphinxemoji
 sphinx-autobuild==2021.3.14
     # via -r docs.in
+sphinx-design==0.2.0
+    # via -r docs.in
 sphinx-hoverxref @ git+https://github.com/readthedocs/sphinx-hoverxref
     # via -r docs.in
 sphinx-intl==2.0.1
@@ -132,3 +135,5 @@ urllib3==1.26.9
 
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools
+
+sphinxcontrib-video @ git+https://github.com/readthedocs/sphinxcontrib-video/