You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
.. This README.rst should work on Github and is also included in the Sphinx documentation project in docs/ - therefore, README.rst uses absolute links for most things so it renders properly on GitHub
8
+
.. This README.rst should work on GitHub and is also included in the Sphinx documentation project in docs/ - therefore, README.rst uses absolute links for most things so it renders properly on GitHub
9
9
10
-
This example shows a Jupyter Book project with Read the Docs. You're encouraged to view it to get inspiration and copy & paste from the files in the source code. If you are using Read the Docs for the first time, have a look at the official `Read the Docs Tutorial <https://docs.readthedocs.io/en/stable/tutorial/index.html>`__.
10
+
This example shows a Jupyter Book project with Read the Docs. You're encouraged to view it to get inspiration and copy & paste from the files in the source code. If you are using Read the Docs for the first time, have a look at the official `Read the Docs Tutorial <https://docs.readthedocs.io/en/stable/tutorial/index.html>`__. If you are using Jupyter Book for the first time, have a look at the `official Jupyter Book documentation <https://jupyterbook.org/en/stable/>`_.
A basic Jupyter Book project lives in ``docs/``. All the ``*.md`` make up sections in the documentation.
13
+
A basic Jupyter Book project lives in ``docs/``. All the ``*.md`` make up sections in the documentation, ``intro.md`` is the starting page and includes this ``README.rst``.
This is the configuration for Jupyter Book which is used to generate a Sphinx-configuration on-the-fly. However, the Sphinx ``conf.py`` file is NOT managed in a git repository, as it is managed by Jupyter Book!
18
-
📍 `docs/requirements.txt <https://github.com/readthedocs-examples/example-jupyter-book/blob/main/docs/requirements.txt>`_ and `docs/requirements.in <https://github.com/readthedocs-examples/example-jupyter-book/blob/main/docs/requirements.in>`_
19
-
Python dependencies are `pinned <https://docs.readthedocs.io/en/latest/guides/reproducible-builds.html>`_ (uses `pip-tools <https://pip-tools.readthedocs.io/en/latest/>`_). Make sure to add your Python dependencies to ``requirements.txt`` or if you choose [pip-tools](https://pip-tools.readthedocs.io/en/latest/), edit ``docs/requirements.in`` and remember to run ``pip-compile docs/requirements.in``.
20
-
🔢 Git tags versioning
21
-
We use a basic versioning mechanism by adding a git tag for every release of the example project. All releases and their version numbers are visible on `example-jupyter-book.readthedocs.io <https://example-jupyter-book.readthedocs.io/en/latest/>`__.
Contents of this ``README.rst`` are visible on Github and included on `the documentation index page <https://example-jupyter-book.readthedocs.io/en/latest/>`_ (Don't Repeat Yourself).
This is the `configuration for Jupyter Book <https://jupyterbook.org/en/stable/customize/config.html>`_ which is used to generate a Sphinx-configuration on-the-fly. However, the Sphinx ``conf.py`` file is NOT managed in a git repository, as it is managed by Jupyter Book!
These dependencies need to be installed for Jupyter Book to work. If you are familiar with Python, you might notice that the dependencies are *not* `pinned <https://docs.readthedocs.io/en/latest/guides/reproducible-builds.html>`_. This is the default method for Jupyter Book - on one hand it gives you the latest version each time Read the Docs builds your documentation; but on the other hand, your build can fail in the future if an incompatible version of ``jupyter-book`` is released.
A floating window (also known as a "tooltip" or "modal dialogue") appears when the mouse curser hovers a cross references to another section of the documentation or another documentation project referenced with Intersphinx.
24
+
🔢 Simplified versioning
25
+
In this example, we maintain a single version of the rendered documentation by automatically building and rendering everything that is added to the ``main`` branch. This is different from many software projects where several `versions of the docs <https://docs.readthedocs.io/en/stable/versions.html>`_ may be published for each new release.
26
+
🔢 Pull Request builds
27
+
Every time a change in a Pull Request on the GitHub repository happens, users can open `an automatically built Pull Request preview <https://docs.readthedocs.io/en/stable/pull-requests.html>`__.
24
28
⁉️ Questions / comments
25
-
If you have questions related to this example, feel free to can ask them as a Github issue `here <https://github.com/readthedocs-examples/example-jupyter-book/issues>`_.
29
+
If you have questions related to this example, feel free to can ask them as a GitHub issue `here <https://github.com/readthedocs-examples/example-jupyter-book/issues>`_.
26
30
27
31
28
32
Example Project usage
29
33
---------------------
30
34
31
-
This project has a standard Sphinx layout which is built by Read the Docs almost the same way that you would build it locally (on your own laptop!).
35
+
This project has a standard Jupyter Book layout which is built by Read the Docs almost the same way that you would build it locally (on your own laptop!).
32
36
33
37
You can build and view this documentation project locally - we recommend that you activate `a local Python virtual environment first <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`_:
34
38
@@ -37,25 +41,11 @@ You can build and view this documentation project locally - we recommend that yo
You can also build the documentation locally with ``make``:
48
-
49
-
.. code-block:: console
50
-
51
-
# Enter the Sphinx project
52
-
cd docs/
53
-
54
-
# Build with make
55
-
make html
56
-
57
-
# Open with your preferred browser, pointing it to the documentation index page
58
-
firefox _build/html/index.html
47
+
# View the docs with for instance firefox
48
+
firefox docs/_build/index.html
59
49
60
50
61
51
Using the example in your own project
@@ -65,17 +55,22 @@ If you are new to Read the Docs, you may want to refer to the `Read the Docs Use
65
55
66
56
If you are copying this code in order to get started with your documentation, you need to:
67
57
68
-
#. place your ``docs/`` folder alongside your Python project. If you are starting a new project, you can adapt the `pyproject.toml` example configuration.
69
-
#. use your existing project repository or create a new repository on Github, GitLab, Bitbucket or another host supported by Read the Docs
58
+
#. use your existing project repository or create a new repository on GitHub, GitLab, Bitbucket or another host supported by Read the Docs
70
59
#. copy ``.readthedocs.yaml`` and the ``docs/`` folder into your project.
60
+
#. if you want to have a README on GitHub, create a ``README.rst`` which will be included in ``index.md``.
61
+
#. if you *do not* want your README from GitHub included in the docs, edit `ìndex.md`` and remove the ``eval-rst`` block that includes it.
62
+
#. if you don't already have a ``.gitignore``, use the one from the project file -- otherwise add these lines::
63
+
64
+
/docs/conf.py
65
+
/docs/_build
66
+
71
67
#. customize all the files, replacing example contents.
72
-
#. add your own Python project, replacing the ``pyproject.toml`` configuration and ``lumache.py`` module.
73
68
#. rebuild the documenation locally to see that it works.
74
69
#. *finally*, register your project on Read the Docs, see `Importing Your Documentation <https://docs.readthedocs.io/en/stable/intro/import-guide.html>`_.
75
70
76
71
77
-
Read the Docs tutorial
72
+
Read the Docs Tutorial
78
73
----------------------
79
74
80
-
To get started with Read the Docs, you may also refer to the `Read the Docs tutorial<https://docs.readthedocs.io/en/stable/tutorial/>`__.
75
+
To get started with Read the Docs, you may also refer to the `Read the Docs Tutorial<https://docs.readthedocs.io/en/stable/tutorial/>`__.
81
76
It provides a full walk-through of building an example project similar to the one in this repository.
Behind the built-in Sphinx extension `intersphinx` is a powerful tool to reference sections in other Sphinx and Jupyter Book documentation projects.
4
+
5
+
You can configure mappings to external Sphinx projects in your Jupyter Book configuration, the `_config.yml` file. In this example project, we have configured `ebp` to reference `https://executablebooks.org/en/latest/`. In the following code examples, we refer to the configured `ebp` mapping and link directly to a section called `tools`.
6
+
7
+
```{tab} MyST (Markdown)
8
+
9
+
```{example}
10
+
We can link to pages in other documentation projects.
11
+
This is a link to the
12
+
[Executable Book project's list of tools they build](ebp:tools)
13
+
```
14
+
15
+
16
+
```{tab} reStructuredText
17
+
18
+
```{example}
19
+
20
+
```{eval-rst}
21
+
We can link to pages in other documentation projects.
22
+
This is a link to the
23
+
:doc:`Executable Book project's list of tools they build <ebp:tools>`
24
+
```
25
+
26
+
```{note}
27
+
In the above `reStructuredText` example, we use `{eval-rst}` to write reST inside a `.md` file (i.e. the one you are reading now). You only need to use this directive if you are writing reST code in a `.md` file.
0 commit comments