{"id":17329749,"url":"https://github.com/melissawm/minimalsphinx","last_synced_at":"2025-04-14T09:04:07.974Z","repository":{"id":43934965,"uuid":"327770843","full_name":"melissawm/minimalsphinx","owner":"melissawm","description":"A repo with a minimal Sphinx example for Python documentation.","archived":false,"fork":false,"pushed_at":"2024-08-05T22:14:21.000Z","size":192,"stargazers_count":56,"open_issues_count":0,"forks_count":38,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-01-29T09:44:55.988Z","etag":null,"topics":["documentation","python"],"latest_commit_sha":null,"homepage":"https://minimalsphinx.readthedocs.io","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/melissawm.png","metadata":{"files":{"readme":"README.md","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":"2021-01-08T01:51:13.000Z","updated_at":"2024-12-17T20:57:54.000Z","dependencies_parsed_at":"2024-01-23T22:44:35.973Z","dependency_job_id":"f3077186-50b2-456b-86b9-5b459f33759c","html_url":"https://github.com/melissawm/minimalsphinx","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/melissawm%2Fminimalsphinx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melissawm%2Fminimalsphinx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melissawm%2Fminimalsphinx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/melissawm%2Fminimalsphinx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/melissawm","download_url":"https://codeload.github.com/melissawm/minimalsphinx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237460856,"owners_count":19313580,"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":["documentation","python"],"created_at":"2024-10-15T14:49:20.271Z","updated_at":"2025-02-06T11:19:23.834Z","avatar_url":"https://github.com/melissawm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# minimalsphinx\n\nSphinx is what is called a documentation generator. This means that it takes a bunch of source files in plain text, and generates a bunch of other awesome things, mainly HTML. For our use case you can think of it as a program that takes in plain text files in reStructuredText format, and outputs HTML.\n\nreST -\u003e Sphinx -\u003e HTML\n\nSo as a user of Sphinx, your main job will be writing these text files. This means that you should be minimally familiar with reStructuredText as a language. It’s similar to Markdown in a lot of ways, if you are already familiar with Markdown.\n\nThis repo contains a very simple example of how to set up and use Sphinx to generate Python documentation.\n\nSee the rendered version of the documentation at [https://minimalsphinx.readthedocs.io](https://minimalsphinx.readthedocs.io)\n\n## Basic instructions\n\n0. Install Python on your machine. Depending on your operating system, the instructions may vary.\n1. Create and activate a virtual environment for your project. You can use conda for this:\n\n   ```bash\n   $ conda env create -f environment.yml\n   $ conda activate minimal-sphinx\n   ```\n\n   Another option is to use virtualenv. Create a\n\n   ```bash\n   $ pip install virtualenv  # not needed if you have used virtualenv before\n   $ virtualenv venv\n   $ source venv/bin/activate\n   ```\n\n   (A subtle difference between both methods is that the virtualenv environment you created lives in the folder where it was created, whereas the conda environment will work in whatever folder you are on.)\n\n2. Install sphinx\n\n\tIf you have used the conda instructions above, you all all set. If you prefer using pip, you can do\n\n\t```bash\n\t$ pip install -r requirements.txt\n\t```\n\n\tThis will install all required packages, including `sphinx` itself and the `furo` Sphinx theme.\n\n3. Initiate sphinx\n\n\tIf you are starting a project from scratch, you can do\n\n\t```bash\n\t$ sphinx-quickstart\n\t```\n\n\tto get an initial file structure and configuration for your documentation. You can set default values for most of the answers, but you should fill your name and the project's name. The final message should say:\n\n\t\u003e Finished: An initial directory structure has been created.\n\n\t\u003e You should now populate your master file /home/melissa/projects/minimalsphinx/index.rst and create other documentation source files. Use the Makefile to build the docs, like so:\n    \u003e     make builder\n    \u003e where \"builder\" is one of the supported builders, e.g. html, latex or linkcheck\n\n\tThis means that once you have your documentation, you can choose in which format to build it to. For example, to build an html version of the docs, you can navigate to the `docs/` folder and use\n\n\t```bash\n\t$ make html\n\t```\n\n\tHowever, if you run this command now, you may see some WARNINGS - this is expected as we haven't actually created any documents to build.\n\n\t(For this repo, this initial configuration has already been run, so you don't need to do it again.)\n\n4. You can check the current folder for a bunch of automatically created files and folders. If you open `_build/html/index.html`, you can see an autogenerated starting point for your documentation. So now, let's create some documents!\n\n## Documenting a Python module\n\nWe'll create a very simple Python module to test our setup. It's a starter Pokédex, containing just the three starter Pokémon from the Kanto region.\n\n### The `index.rst` file and the reStructuredText format\n\nAfter running `sphinx-quickstart`, an `index.rst` file is created that serves as the entry-point to your module documentation (unless you want to customize this - we'll see how you can do that below). It will likely contain only a basic structure in a [reStructuredText format](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). reStructuredText, or reST, is a markup syntax that allows you to autogenerate documentation, including inline markup, custom content and powerful linking and referencing features.\n\nThe standard reST inline markup consists of\n- one asterisk: `*text*` for emphasis (italics),\n- two asterisks: `**text**` for strong emphasis (boldface), and\n- backquotes: `` `text` `` for code samples.\n\nIn addition, reST also implements [directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives), which are blocks of explicit markup which can have arguments, options and content. We'll see some examples of that in our module documentation.\n\nFor now, you can see some directives in the `index.rst` file: `toctree` is a reStructuredText directive; `maxdepth` and `caption` are options for this directive, and their values are `2` and `Contents:`. In addition, you can see the `:ref:` *role* in this file. Sphinx implements [interpreted text roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html) to insert semantic markup into documents. For example, ``:ref:`search` `` implements the role `ref` with the content `search` - in this particular case, we are cross-referencing a location, in this case creating a link to the document with label `search`.\n\nWe'll see concrete examples of this in the NumPy documentation, but you can check out a [nice summary of reST syntax](https://sphinx-tutorial.readthedocs.io/step-1/) and a longer [reST primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html).\n\n### The `conf.py` file\n\nIn order to properly autogenerate our documentation, we must edit a configuration file called `conf.py`, which is created by `sphinx-quickstart` with default values. You should see this in the root folder of your project.\n\nFor now, the first thing to customize is the project name and author, if you have to. After that, we'll add `'venv'` to the `exclude_patterns` list, if you're using venv to manage your developer environment. With this basic configuration we create the documentation with `make html`.\n\n### Generating your module documentation\n\nRight now, there's nothing in your rendered documentation. Let's fix that.\n\nWhen documenting Python code, it is common to write *docstrings*. Sphinx supports the inclusion of docstrings from your modules with an extension called [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc).\n\nIn order to use autodoc, you need to activate it in `conf.py` by writing\n\n```\nextensions = ['sphinx.ext.autodoc']\n```\n\nYou can then document whole classes or even modules automatically, using member options for the auto directives, like\n\n```\n.. automodule:: io\n   :members:\n```\n\nNote that autodoc needs to import your modules in order to extract the docstrings. Therefore, you must add the appropriate path to `sys.path` in your `conf.py`.\n\n### doctests\n\nAnother extension that is helpful is [sphinx.ext.doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html). This allows you to add tests *to your docstrings*. All you need to do is add `'sphinx.ext.doctest'` to your `extensions` variable in `conf.py`. After this, you can add doctests as examples in your docstrings. You can then run\n\n```\n$ make doctest\n```\n\nto see the results.\n\n### Adding custom pages\n\nBecause we want to add more to our documentation than just the docstrings, let's add some custom pages to our project.\n\n1. Move the API documentation to a separate page.\n\n   First, let's create a new `apidocs.rst` file and move the `automodule` directive to this new file. After this, we'll add `apidocs` to our ToC Tree - our Table of Contents in the main `index.rst` file.\n\n2. Add a Quickstart page to our documentation\n\n   We'll write the *Quickstart* page separately.\n\n### Intersphinx\n\nFinally, we'll check the `sphinx.ext.intersphinx` extension. Adding this to our extensions list, we can refer to other project's documentation labels easily by using their *intersphinx mapping*. For an example, check the **Base Stats** section in the Quickstart document of this package.\n\n## References\n\n- [Sphinx tutorial](https://www.sphinx-doc.org/en/master/tutorial/index.html)\n- [Sphinx documentation](https://www.sphinx-doc.org/en/master/)\n- [Matplotlib Sphinx tutorial](https://matplotlib.org/sampledoc/)\n- [Sphinx tutorial](https://sphinx-tutorial.readthedocs.io/) by Eric Holscher\n- [A beginner's guide to writing documentation](https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/), also by Eric Holscher\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelissawm%2Fminimalsphinx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmelissawm%2Fminimalsphinx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmelissawm%2Fminimalsphinx/lists"}