{"id":15706365,"url":"https://github.com/cdeil/sphinx-tutorial","last_synced_at":"2025-08-09T18:31:13.595Z","repository":{"id":142038964,"uuid":"54321854","full_name":"cdeil/sphinx-tutorial","owner":"cdeil","description":"A little Sphinx documentation tutorial at the PyAstro16 workshop","archived":false,"fork":false,"pushed_at":"2016-03-24T01:34:05.000Z","size":122,"stargazers_count":5,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-24T18:15:32.857Z","etag":null,"topics":["python","sphinx-doc","tutorial"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cdeil.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-20T14:26:30.000Z","updated_at":"2020-01-02T18:15:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"516289f0-745b-4738-a791-be5beeef8101","html_url":"https://github.com/cdeil/sphinx-tutorial","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdeil%2Fsphinx-tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdeil%2Fsphinx-tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdeil%2Fsphinx-tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdeil%2Fsphinx-tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdeil","download_url":"https://codeload.github.com/cdeil/sphinx-tutorial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229313138,"owners_count":18053707,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","sphinx-doc","tutorial"],"created_at":"2024-10-03T20:22:26.836Z","updated_at":"2024-12-12T00:31:22.601Z","avatar_url":"https://github.com/cdeil.png","language":"Python","readme":"Sphinx tutorial\n===============\n\nWhat is this?\n+++++++++++++\n\n* A one hour `Sphinx \u003chttp://www.sphinx-doc.org/\u003e`__ tutorial introduction.\n* By `Christoph Deil \u003chttps://github.com/cdeil\u003e`__ and `Stuart Mumford \u003chttps://github.com/cadair\u003e`__ .\n* March 21, 2016 at `PyAstro16 \u003chttp://python-in-astronomy.github.io/2016/\u003e`__ .\n\nYou will learn how to add Sphinx documentation to a Python package (using the\nexample ``astrospam`` Python package in this repo).\n\nThe focus is exclusively on technical aspects how to work with Sphinx. We will\n**not** have time to talk about how to write good documentation, i.e. what\ncontent to create and how to structure it.\n\nYou are encouraged to follow along, i.e. try out every step on your computer\nafter we demo it.\n\nBefore we start:\n\n* Who has run Sphinx before (i.e. run ``sphinx-build`` or ``make html`` or ``python setup.py build_sphinx``)?\n* Who has set up Sphinx before (i.e. run ``sphinx-quickstart``, edited ``docs/conf.py``)?\n\n**If you have a question, or something isn't working for you, or if I'm going too\nfast, please feel free to interrupt us at any time!**\n\nOverview\n++++++++\n\n1. `Introduction \u003chttps://github.com/cdeil/sphinx-tutorial#1-introduction\u003e`__\n2. `Installation \u003chttps://github.com/cdeil/sphinx-tutorial#2-installation\u003e`__\n3. `Quickstart \u003chttps://github.com/cdeil/sphinx-tutorial#3-quickstart\u003e`__\n4. `RST \u003chttps://github.com/cdeil/sphinx-tutorial#4-rst\u003e`__\n5. `Autodoc \u003chttps://github.com/cdeil/sphinx-tutorial#5-autodoc\u003e`__\n6. `Theme \u003chttps://github.com/cdeil/sphinx-tutorial#6-theme\u003e`__\n7. `Final comments \u003chttps://github.com/cdeil/sphinx-tutorial#7-final-comments\u003e`__\n\n1. Introduction\n---------------\n\nWe'll start with a quick overview of Sphinx and related things by having a\nlook at the following web pages.\n\nIf you want to learn more, please go back and read the info on those pages\nafter the tutorial on your own.\n\n* We won't talk about `this Sphinx \u003chttps://upload.wikimedia.org/wikipedia/commons/thumb/f/f6/Great_Sphinx_of_Giza_-_20080716a.jpg/800px-Great_Sphinx_of_Giza_-_20080716a.jpg\u003e`_.\n  (I don't know why the Sphinx documentation generator was given that name.)\n* To get some basic info on Sphinx, read the\n  `Wikipedia on Sphinx (documentation generator) \u003chttps://en.wikipedia.org/wiki/Sphinx_(documentation_generator)\u003e`__\n  or the welcome page of the Sphinx website at http://www.sphinx-doc.org/ .\n* The most useful pages in the Sphinx documentation to get started are the\n  `Sphinx tutorial \u003chttp://www.sphinx-doc.org/en/stable/tutorial.html\u003e`__\n  and the `reStructuredText Primer \u003chttp://www.sphinx-doc.org/en/stable/rest.html\u003e`__\n* Almost all Python projects use reStructured text (RST) and Sphinx for documentation.\n  Examples: `Python \u003chttps://docs.python.org/3/\u003e`__\n  `Astropy \u003chttp://astropy.readthedocs.org/en/latest/\u003e`__,\n  `Astroplan \u003chttp://astroplan.readthedocs.org/\u003e`__\n* As the `Wikipedia article on reStructuredText (RST) \u003chttps://en.wikipedia.org/wiki/ReStructuredText\u003e`__\n  explains, RST is a markup language (like LaTeX or Markdown) that is mostly used for Python docstrings (in ``.py`` files)\n  and high-level documentation (in ``.rst`` files).\n* Sphinx is the tool that takes RST as input and produces HTML or PDF as output.\n  To be more precise, Sphinx is a Python package that is mostly used via the command line tools\n  ``sphinx-quickstart`` and ``sphinx-build`` (which again you typically invoke via a ``Makefile``).\n* `Python docstrings \u003chttps://en.wikipedia.org/wiki/Docstring#Python\u003e`__ are extracted by\n  the Sphinx \"autodoc\" feature to auto-generate API (application programming interface) docs.\n  There's a few different formats for docstrings in use that Sphinx supports.\n* The one all scientific Python packages (Numpy, Scipy, Astropy, ...) use is called the\n  `Numpy docstring standard \u003chttps://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt\u003e`__\n  which as added as a built-in Sphinx extension called\n  `sphinx.ext.napoleon \u003chttp://www.sphinx-doc.org/en/stable/ext/napoleon.html\u003e`__\n  (I don't know why it was called Napoleon.)\n* Once documentation is set up for your package, it's typically easy to generate HTML\n  output by just running ``make html`` which calls ``sphinx-build``,\n  or by executing ``python setup.py build_sphinx`` which runs the Sphinx build.\n  Then you can look at the output by just opening up ``index.html`` in some output\n  directory where the HTML docs have been generated.\n  Working on documentation is then a matter of editing ``.rst`` or ``.py`` files,\n  running ``make html`` and checking the HTML output or console for errors and warnings.\n* Finally, if you want to host the generated HTML, the free https://readthedocs.org/\n  and https://pages.github.com/ services are good options.\n  We won't have time to cover those today, feel free to ask us after if you want to\n  learn how they work or want help to set it up for your project.\n\nLet's go ahead with our hands-on introduction to Sphinx and start using it ...\n\n2. Installation\n---------------\n\nOpen a terminal and type ``sphinx\u003cTAB\u003e``. If this lists ``sphinx-*`` commands\n(e.g ``sphinx-quickstart`` or ``sphinx-build``), you have Sphinx installed.\nType ``sphinx-build --version`` to check the Sphinx version number.\n\nThe latest stable version is 1.3.\nIf you have 1.2 or older, I'd suggest you update now e.g. using::\n\n    $ pip install --upgrade sphinx\n    $ conda install sphinx\n\nLater on we'll use the `sphinx_rtd_theme \u003chttps://github.com/snide/sphinx_rtd_theme\u003e`__ .\nPlease install it now via::\n    \n    $ pip install sphinx_rtd_theme\n\nBefore we continue, everyone please check that you're set up::\n    \n    $ sphinx-build --version\n    Sphinx (sphinx-build) 1.3.6\n    $ python -c 'import sphinx_rtd_theme'\n    # Should give no output.\n    # If you get an ImportError, `sphinx_rtd_theme` isn't installed correctly.\n\n3. Quickstart\n-------------\n\nLet's say you have a Python project consisting of a few ``.py`` files,\nand would like to use Sphinx to generate HTML or PDF documentation for it.\n\nExample package\n+++++++++++++++\n\nAs an example for today's tutorial, please grab this repo::\n\n    $ git clone https://github.com/cdeil/sphinx-tutorial\n    $ cd sphinx-tutorial\n\nAs you can see, there is a Python package called ``astrospam``::\n\n    $ tree .\n    .\n    ├── LICENSE\n    ├── README.rst\n    └── astrospam\n        ├── __init__.py\n        ├── ham.py\n        ├── pyastro16.py\n        └── spam.py\n\nBut there's no HTML documentation for it. Let's change that!\n\nsphinx-quickstart\n+++++++++++++++++\n\nTo add Sphinx documentation, you run `sphinx-quickstart \u003chttp://www.sphinx-doc.org/en/stable/invocation.html#invocation\u003e`__\n\nThis will prompt you for some information and then generate a few of files.\n\nFor most questions you can just hit ``ENTER`` to accept the default. These are\nthe questions where you don't take the default, but actually put something::\n    \n    $ sphinx-quickstart\n\n    Welcome to the Sphinx 1.3.6 quickstart utility.\n\n    \u003e Root path for the documentation [.]: docs\n    \u003e Project name: astrospam\n    \u003e Author name(s): Astrospam developers\n    \u003e Project version: 0.1\n    \u003e autodoc: automatically insert docstrings from modules (y/n) [n]: y\n\n    Finished: An initial directory structure has been created.\n\nThe tool created the following files:\n\n* ``docs/conf.py`` -- Sphinx configuration file (a Python file)\n* ``docs/index.rst`` -- Name of your master docs page (a reStructuredText, aka RST file)\n* ``docs/Makefile`` -- Makefile as convenience to run Sphinx (for Linux and Mac OS X)\n* ``docs/make.bat`` -- Makefile for Windows\n\nAnd the following empty directories:\n\n* ``docs/_build`` -- This is where all output files (e.g. HTML) will go when Sphinx runs.\n* ``docs/_static`` -- A place for static files, e.g. images or css (we won't use it)\n* ``docs/_templates`` -- A place for template files (we won't use it)\n\nsphinx-build\n++++++++++++\n\nNow we're all set up to generate HTML docs::\n\n    $ cd docs\n    $ make html\n    sphinx-build -b html -d _build/doctrees   . _build/html\n    Running Sphinx v1.3.6\n    making output directory...\n    loading pickled environment... not yet created\n    building [mo]: targets for 0 po files that are out of date\n    building [html]: targets for 1 source files that are out of date\n    updating environment: 1 added, 0 changed, 0 removed\n    reading sources... [100%] index                                                                        \n    looking for now-outdated files... none found\n    pickling environment... done\n    checking consistency... done\n    preparing documents... done\n    writing output... [100%] index                                                                         \n    generating indices... genindex\n    writing additional pages... search\n    copying static files... done\n    copying extra files... done\n    dumping search index in English (code: en) ... done\n    dumping object inventory... done\n    build succeeded.\n\n    Build finished. The HTML pages are in _build/html.\n\nNow open up ``_build/html/index.html`` in your webbrowser.\n\nOn Mac you can do::\n\n    $ open _build/html/index.html\n\nSphinx has generated a documentation webpage for you (with a sidebar, search\nfield, main content area, footer)!\n\nThere's some other things you can do. Type ``make`` or ``make help`` to find out::\n\n    $ make\n    Please use `make \u003ctarget\u003e' where \u003ctarget\u003e is one of\n      html       to make standalone HTML files\n      dirhtml    to make HTML files named index.html in directories\n      singlehtml to make a single large HTML file\n      pickle     to make pickle files\n      json       to make JSON files\n      htmlhelp   to make HTML files and a HTML help project\n      qthelp     to make HTML files and a qthelp project\n      applehelp  to make an Apple Help Book\n      devhelp    to make HTML files and a Devhelp project\n      epub       to make an epub\n      latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter\n      latexpdf   to make LaTeX files and run them through pdflatex\n      latexpdfja to make LaTeX files and run them through platex/dvipdfmx\n      text       to make text files\n      man        to make manual pages\n      texinfo    to make Texinfo files\n      info       to make Texinfo files and run them through makeinfo\n      gettext    to make PO message catalogs\n      changes    to make an overview of all changed/added/deprecated items\n      xml        to make Docutils-native XML files\n      pseudoxml  to make pseudoxml-XML files for display purposes\n      linkcheck  to check all external links for integrity\n      doctest    to run all doctests embedded in the documentation (if enabled)\n      coverage   to run coverage check of the documentation (if enabled)\n    \nIf you have ``pdflatex`` installed, you can try making a PDF version of your docs::\n\n    $ make latexpdf\n    sphinx-build -b latex -d _build/doctrees   . _build/latex\n    Running Sphinx v1.3.6\n    making output directory...\n    loading pickled environment... done\n    building [mo]: targets for 0 po files that are out of date\n    building [latex]: all documents\n    updating environment: 0 added, 0 changed, 0 removed\n    looking for now-outdated files... none found\n    processing astrospam.tex... index \n    resolving references...\n    writing... done\n    copying TeX support files...\n    done\n    build succeeded.\n    Running LaTeX files through pdflatex...\n\n    ... 1000 lines of horrible LaTeX log output ... \n\n    Output written on astrospam.pdf (7 pages, 43725 bytes).\n    Transcript written on astrospam.log.\n    pdflatex finished; the PDF files are in _build/latex.\n\nOpen up ``_build/latex/astrospam.pdf`` and have a look::\n\n    $ open _build/latex/astrospam.pdf\n\nWe're all set up to write some documentation ...\n\n4. RST\n------\n\nNow let's write some documentation.\n\nIntroduction\n++++++++++++\n\nThis is done by adding text to ``docs/index.rst``, or by adding extra ``.rst``\ntext files in ``docs`` and writing text using RST format there.\n\nWriting documentation is a cycle similar to writing code:\n\n1. Edit ``.rst`` files\n2. Run ``make html``\n3. Check output HTML files\n\nFor the following exercises, and generally while learning how to write RST,\nit's very helpful to have the \"reStructuredText Primer\" page from the Sphinx docs open:\nhttp://www.sphinx-doc.org/en/stable/rest.html\n\nExercise 1\n++++++++++\n\nLet's do the documentation writing cycle once:\n\n1. Edit ``index.rst`` and add this line after the title::\n\n    Hello world!\n\n2. Run ``make html``\n3. Refresh the browser and watch the text appear in the HTML output.\n\nExercise 2\n++++++++++\n\n* Add a `sub-section \u003chttp://www.sphinx-doc.org/en/stable/rest.html#sections\u003e`__\n  called \"Getting started\".\n* Add the `paragraph \u003chttp://www.sphinx-doc.org/en/stable/rest.html#paragraphs\u003e`__\n  \"The ``astrospam`` module provides:\" followed by a `list \u003chttp://www.sphinx-doc.org/en/stable/rest.html#lists-and-quote-like-blocks\u003e`__\n  with entries ``Ham`` and ``spam``.\n* Add a `code example \u003chttp://www.sphinx-doc.org/en/stable/rest.html#source-code\u003e`__::\n\n    $ python\n    \u003e\u003e\u003e import astrospam\n    \u003e\u003e\u003e astrospam.spam()\n    Spam\n    Spam\n    Spam\n    \u003e\u003e\u003e exit()\n\nExercise 3\n++++++++++\n\n* Add a sub-page ``docs/tutorial.rst`` and copy \u0026 paste the following content there::\n\n    Tutorial\n    ========\n\n    This is the ``astrospam`` tutorial.\n\n    Part 1\n    ------\n\n    Spam, spam, spam ...\n\n    Part 2\n    ------\n\n    More spam!\n\n    https://youtu.be/anwy2MPT5RE\n\nNow add that page to the `toctree \u003chttp://www.sphinx-doc.org/en/stable/markup/toctree.html\u003e`__\ndirective in ``index.rst``::\n    \n    .. toctree::\n       :maxdepth: 2\n\n       tutorial\n\n\nExercise 4\n++++++++++\n\nLet's see what happens if we make an ``RST`` formatting mistake.\n\nRemove some underline characters from the title::\n\n    Welcome to astrospam's documentation!\n    ============================\n\nSphinx will emit a warning pointing out the file and line number where the problem is\nand give a helpful message what the problem is::\n\n    docs/index.rst:7: WARNING: Title underline too short.\n\nThe HTML output will still be OK .. it's just a warning.\n\nExercise 5\n++++++++++\n\nLet's see what happens if you make an error in a Sphinx directive.\n\nE.g. you could change the ``toctree`` directive in ``index.rst`` to ``toctreeeeeee``:\n\n    .. toctreeeeeee::\n       :maxdepth: 2\n\nNow you'll get an error an the TOC will be missing in the output.\n\n5. Autodoc\n----------\n\nRun these commands::\n\n  mkdir -p docs/_templates/autosummary\n  wget https://raw.githubusercontent.com/astropy/package-template/a956da77759743b06db99d207b8e1e1a9eaf8a87/docs/_templates/autosummary/base.rst\n  wget https://raw.githubusercontent.com/astropy/package-template/a956da77759743b06db99d207b8e1e1a9eaf8a87/docs/_templates/autosummary/class.rst\n  wget https://raw.githubusercontent.com/astropy/package-template/a956da77759743b06db99d207b8e1e1a9eaf8a87/docs/_templates/autosummary/module.rst\n\n\nTODO: link from docstrings to docs in RST file and the other way around.\n\nNote that Sphinx autodoc imports the Python module and accesses\ndocstrings stored in ``__doc__`` attributes. This means that\nmodule-level and class-level code is executed.\n\nTODO: Illustrate by adding print statements.\nTODO: Add code that throws an exception (e.g. ``import spam`` or ``1/0`` or a ``SyntaxError``)\nand show the resulting Sphinx error message.\n\nExplain about `__all__`\n\n6. Theme\n--------\n\nTODO: show how to change to the readthedocs template and what changes.\n\n7. Final comments\n-----------------\n\n* We hope that this tutorial gave you a basic understanding of what Sphinx is,\n  how it works, and how you use it to generate the documentation for Python\n  projects.\n* You should now be able to contribute to the documentation of existing\n  Python projects and maybe even be able to set up Sphinx for your own\n  package (e.g. by copy \u0026 pasting the working `package-template \u003chttps://github.com/astropy/package-template\u003e`__ setup).\n* There's many things we didn't cover that will come up if you start contributing\n  to Sphinx documentation for projects like Astropy or Astropy-affiliated packages:\n  plot directive, setup.py integration, doctests, ...\n* Sphinx, like other documentation generators such as LaTeX or Doxygen, is a\n  very complicated, and extremely extensible and customisable tool.\n  Even with years of experience you can easily get stuck with an uncomprehensible\n  error message and get frustrated.\n  Don't be shy to ask for help!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdeil%2Fsphinx-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdeil%2Fsphinx-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdeil%2Fsphinx-tutorial/lists"}