summaryrefslogtreecommitdiffstats
path: root/doc/tutorial/getting-started.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
commitcf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch)
tree18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/tutorial/getting-started.rst
parentInitial commit. (diff)
downloadsphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz
sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/tutorial/getting-started.rst')
-rw-r--r--doc/tutorial/getting-started.rst120
1 files changed, 120 insertions, 0 deletions
diff --git a/doc/tutorial/getting-started.rst b/doc/tutorial/getting-started.rst
new file mode 100644
index 0000000..5cf0b38
--- /dev/null
+++ b/doc/tutorial/getting-started.rst
@@ -0,0 +1,120 @@
+Getting started
+===============
+
+Setting up your project and development environment
+---------------------------------------------------
+
+In a new directory, create a file called ``README.rst`` with the following
+content.
+
+.. code-block:: rst
+ :caption: README.rst
+
+ Lumache
+ =======
+
+ **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
+ creates recipes mixing random ingredients.
+
+It is a good moment to create a Python virtual environment and install the
+required tools. For that, open a command line terminal, ``cd`` into the
+directory you just created, and run the following commands:
+
+.. code-block:: console
+
+ $ python -m venv .venv
+ $ source .venv/bin/activate
+ (.venv) $ python -m pip install sphinx
+
+.. note::
+
+ The installation method used above is described in more detail in
+ :ref:`install-pypi`. For the rest of this tutorial, the instructions will
+ assume a Python virtual environment.
+
+If you executed these instructions correctly, you should have the Sphinx command
+line tools available. You can do a basic verification running this command:
+
+.. code-block:: console
+
+ (.venv) $ sphinx-build --version
+ sphinx-build 4.0.2
+
+If you see a similar output, you are on the right path!
+
+Creating the documentation layout
+---------------------------------
+
+Then from the command line, run the following command:
+
+.. code-block:: console
+
+ (.venv) $ sphinx-quickstart docs
+
+This will present to you a series of questions required to create the basic
+directory and configuration layout for your project inside the ``docs`` folder.
+To proceed, answer each question as follows:
+
+- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without
+ quotes) and press :kbd:`Enter`.
+- ``> Project name``: Write "``Lumache``" (without quotes) and press
+ :kbd:`Enter`.
+- ``> Author name(s)``: Write "``Graziella``" (without quotes) and press
+ :kbd:`Enter`.
+- ``> Project release []``: Write "``0.1``" (without quotes) and press
+ :kbd:`Enter`.
+- ``> Project language [en]``: Leave it empty (the default, English) and press
+ :kbd:`Enter`.
+
+After the last question, you will see the new ``docs`` directory with the
+following content.
+
+.. code-block:: text
+
+ docs
+ ├── build
+ ├── make.bat
+ ├── Makefile
+ └── source
+ ├── conf.py
+ ├── index.rst
+ ├── _static
+ └── _templates
+
+The purpose of each of these files is:
+
+``build/``
+ An empty directory (for now) that will hold the rendered documentation.
+
+``make.bat`` and ``Makefile``
+ Convenience scripts to simplify some common Sphinx operations, such as
+ rendering the content.
+
+``source/conf.py``
+ A Python script holding the configuration of the Sphinx project. It contains
+ the project name and release you specified to ``sphinx-quickstart``, as well
+ as some extra configuration keys.
+
+``source/index.rst``
+ The :term:`root document` of the project, which serves as welcome page and
+ contains the root of the "table of contents tree" (or *toctree*).
+
+Thanks to this bootstrapping step, you already have everything needed to render
+the documentation as HTML for the first time. To do that, run this command:
+
+.. code-block:: console
+
+ (.venv) $ sphinx-build -b html docs/source/ docs/build/html
+
+And finally, open ``docs/build/html/index.html`` in your browser. You should see
+something like this:
+
+.. figure:: /_static/tutorial/lumache-first-light.png
+ :width: 80%
+ :align: center
+ :alt: Freshly created documentation of Lumache
+
+ Freshly created documentation of Lumache
+
+There we go! You created your first HTML documentation using Sphinx.
+Now you can start :doc:`customizing it </tutorial/first-steps>`.