Example projects
================

* Need inspiration?
* Want to bootstrap a new documentation project?
* Want to showcase your own solution?

The following example projects show a rich variety of uses of Read the Docs.
You can use them for inspiration, for learning and for recipes to start your own documentation projects.
View the *rendered* version of each project and then head over to the Git source to see how it's done and reuse the code.

Sphinx and MkDocs examples
--------------------------

.. list-table::
   :header-rows: 1
   :widths: 20 20 40 20

   * - Topic
     - Framework
     - Links
     - Description
   * - Basic Sphinx
     - Sphinx
     - `[Git] <https://github.com/readthedocs-examples/example-sphinx-basic/>`__ `[Rendered] <https://example-sphinx-basic.readthedocs.io/en/latest/>`__
     - Sphinx example with versioning and Python doc autogeneration
   * - Basic MkDocs
     - MkDocs
     - `[Git] <https://github.com/readthedocs-examples/example-mkdocs-basic/>`__ `[Rendered] <https://example-mkdocs-basic.readthedocs.io/en/latest/>`__
     - Basic example of using MkDocs
   * - Jupyter Book
     - Jupyter Book and Sphinx
     - `[Git] <https://github.com/readthedocs-examples/example-jupyter-book/>`__ `[Rendered] <https://example-jupyter-book.readthedocs.io/>`__
     - Jupyter Book with popular integrations configured


Real-life examples
------------------

.. image:: _static/images/awesome-list.svg
  :alt: Awesome List badge
  :target: https://github.com/readthedocs-examples/awesome-read-the-docs

We maintain an **Awesome List** where you can contribute new shiny examples of using Read the Docs.
Please refer to the instructions on how to submit new entries on `Awesome Read the Docs Projects <https://github.com/readthedocs-examples/awesome-read-the-docs>`__.


Contributing an example project
-------------------------------

We would love to add more examples that showcase features of Read the Docs or great tools or methods to build documentation projects.

We **require** that an example project:

* is **hosted and maintained by you** in its own Git repository, ``example-<topic>``.
* contains a README.
* uses a ``.readthedocs.yaml`` configuration.
* is added to the above list by **opening a PR** targeting `examples.rst <https://github.com/readthedocs/readthedocs.org/blob/main/docs/user/examples.rst>`_.


We **recommend** that your project:

* has **continuous integration and PR builds**.
* is **versioned** as a real software project, i.e. using git tags.
* covers your most important scenarios, but references external real-life projects whenever possible.
* has a minimal tech stack -- or whatever you feel comfortable about maintaining.
* copies from an existing example project as a template to get started.

We're excited to see what you come up with!