Tutorial: Build your first project
**********************************

In this tutorial you will build a simple documentation project using
Sphinx, and view it in your browser as HTML.  The project will include
narrative, handwritten documentation, as well as autogenerated API
documentation.

The tutorial is aimed towards Sphinx newcomers willing to learn the
fundamentals of how projects are created and structured.  You will
create a fictional software library to generate random food recipes
that will serve as a guide throughout the process, with the objective
of properly documenting it.

To showcase Sphinx capabilities for code documentation you will use
Python, which also supports *automatic* documentation generation.

Note:

  Several other languages are natively supported in Sphinx for
  *manual* code documentation, however they require extensions for
  *automatic* code documentation, like Breathe.

To follow the instructions you will need access to a Linux-like
command line and a basic understanding of how it works, as well as a
working Python installation for development, since you will use
*Python virtual environments* to create the project.

* Getting started

  * Setting up your project and development environment

  * Creating the documentation layout

* First steps to document your project using Sphinx

  * Building your HTML documentation

  * Building your documentation in other formats

* More Sphinx customization

  * Enabling a built-in extension

  * Using a third-party HTML theme

* Narrative documentation in Sphinx

  * Structuring your documentation across multiple pages

  * Adding cross-references

* Describing code in Sphinx

  * Python

    * Documenting Python objects

    * Cross-referencing Python objects

    * Including doctests in your documentation

  * Other languages (C, C++, others)

    * Documenting and cross-referencing objects

* Automatic documentation generation from code

  * Reusing signatures and docstrings with autodoc

  * Generating comprehensive API references

* Appendix: Deploying a Sphinx project online

  * Sphinx-friendly deployment options

  * Embracing the "Docs as Code" philosophy

  * Publishing your documentation sources

    * GitHub

    * GitLab

  * Publishing your HTML documentation

    * Read the Docs

    * GitHub Pages

    * GitLab Pages

* Where to go from here
