.. Intro to Documentation with Sphinx and reStructuredText documentation master file, created by sphinx-quickstart on Sun May 2 12:31:31 2021. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to Intro to Documentation with Sphinx and reStructuredText's documentation! =================================================================================== .. admonition:: info This tutorial was prepared for `PyCon 2021 `_ by `Mariatta `_. Tutorial Description -------------------- The success of Python and open source libraries is not separable from the availability of good documentation. Reading documentation is one of the first things a user of the open source library has to do. In the Python open source community, documentation is often written using reStructuredText markup language, and built with Sphinx. The official Python documentation and Python Enhancements Proposals (PEPs) are all written using reStructuredText. Being able to write documentation using reStructuredText becomes a necessary skill for any aspiring Python open source contributors and maintainers. Yet, reStructuredText itself can be seen as a barrier into contributing to open source, since it is not as straightforward as Markdown. Compared to Markdown, reStructuredText is not as widely adopted outside of the Python community. Don’t let this discourage you! Let’s break down this barrier! reStructuredText is not as complicated as you might think. You can learn it! In this tutorial, we'll go through various useful features of reStructuredText. You will learn how to create and build a documentation project using Sphinx. Not only will you learn a new skill, you can also confidently start contributing to open source projects by helping to improve their documentation. Agenda ------ .. csv-table:: :header: "Topic", "Duration" "Introductions", "5 minutes" "Intro to reStructuredText and Sphinx", "10 minutes" "Build a Sphinx project", "10 minutes (assuming you've pre-installed prior to attending)" "First steps with reStructuredText", "20-30 minutes" "break", "15 minutes" "Using Sphinx Roles and Directives", "20-30 minutes" "Sphinx Extensions", "20-30 minutes" "break", "15 minutes" "Doc Hosting", "" "Common Issues, Q&A", "" Code of Conduct --------------- `PyCon`_'s Code of Conduct applies and will be enforced. .. raw:: html .. toctree:: :maxdepth: 2 :caption: Contents: docs_in_python sphinx_first_steps rst_intro sphinx_roles sphinx_extensions docs_hosting .. toctree:: :maxdepth: 2 :caption: Appendix: common_issues thanks license GitHub Repository .. toctree:: :caption: Contributing: :hidden: .. _PyCon: https://us.pycon.org/2021/about/code-of-conduct/