{"id":13398277,"url":"https://github.com/icgood/continuous-docs","last_synced_at":"2026-01-28T00:26:06.246Z","repository":{"id":36878402,"uuid":"41185385","full_name":"icgood/continuous-docs","owner":"icgood","description":"Tutorial and example package for continuous documentation generation in Python.","archived":false,"fork":false,"pushed_at":"2020-08-24T14:07:55.000Z","size":875,"stargazers_count":305,"open_issues_count":0,"forks_count":15,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-07-31T19:15:46.457Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/icgood.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}},"created_at":"2015-08-22T01:50:02.000Z","updated_at":"2024-02-26T10:46:53.000Z","dependencies_parsed_at":"2022-06-28T20:01:19.650Z","dependency_job_id":null,"html_url":"https://github.com/icgood/continuous-docs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icgood%2Fcontinuous-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icgood%2Fcontinuous-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icgood%2Fcontinuous-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icgood%2Fcontinuous-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icgood","download_url":"https://codeload.github.com/icgood/continuous-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243511658,"owners_count":20302593,"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":[],"created_at":"2024-07-30T19:00:21.647Z","updated_at":"2026-01-28T00:26:06.197Z","avatar_url":"https://github.com/icgood.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"Python Continuous Documentation\n===============================\n\n[![Build Status](https://travis-ci.com/icgood/continuous-docs.svg?branch=main)](https://travis-ci.com/icgood/continuous-docs)\n[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://icgood.github.io/continuous-docs/)\n\n## Introduction\n\nIf you own a Python library that uses [Sphinx formatted][1] docstrings, it's\neasy to get started turning these docstrings into beautiful HTML, hosted on\n[GitHub Pages][4], updated every time you push to GitHub.\n\nThis repository is intended to be a working example of this method, check out\n[the docs][2].\n\nThis tutorial uses [Travis CI][9], but there is an older version\n[written for Jenkins](https://github.com/icgood/continuous-docs/tree/jenkins).\n\n#### Why not use [ReadTheDocs][8]?\n\nPlease do! This tutorial simply provides an alternative.\n\n## Setting Up Your Project\n\n### Installation\n\nAs always, I suggest using a [virtualenv][3] for local Python development.\nInside your virtualenv, run:\n\n    pip install sphinx\n\n### Setup\n\nCreate a `doc` directory in your project, we'll add it to git later:\n\n```bash\nmkdir -p doc\ncd doc\n```\n\nCreate the basic configuration and file structure:\n\n    sphinx-quickstart\n\nThere are several questions you need to give a non-default answer to:\n\n    \u003e Separate source and build directories (y/N) [n]: y\n    \u003e Project name: yourproject\n    \u003e Author name(s): Your Name\n    \u003e Project version: 1.2.3\n    \u003e autodoc: automatically insert docstrings from modules (y/N) [n]: y\n    \u003e intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y\n\n### Creating the Doc Layout\n\nWhen running `sphinx-quickstart`, you specified `index.rst` as the starting\npoint for your documentation pages. With Sphinx, you'll need every page linked\neither directly or indirectly from `index.rst` using the `.. toctree::`\ndirective. Let's consider the following Python package:\n\n    docpkg/__init__.py\n    docpkg/main.py\n    docpkg/config.py\n\nOne package, three modules. Replace your `index.rst` with the following:\n\n```rst\n``docpkg`` Package\n==================\n\n.. automodule:: docpkg\n   :members:\n\n-------------------\n\n**Sub-Modules:**\n\n.. toctree::\n\n   docpkg.main\n   docpkg.config\n```\n\nNow we're going to create two more files, `docpkg.main.rst` and\n`docpkg.config.rst`.  I'll give you `docpkg.main.rst`, create\n`docpkg.config.rst` the same way:\n\n```rst\n``docpkg.main`` Module\n========================\n\n.. automodule:: docpkg.main\n   :members:\n```\n\nAs you add more modules to your project, they need to be added to the\ndocumentation structure. You can obviously put more than one `.. automodule::`\non a page, at your discretion.\n\n### Building the Docs Locally\n\nOnce you have your doc layout created, you can build your documentation from\nthe `doc/` directory with:\n\n    make html\n\nTry navigating to `doc/build/html/index.html` in your browser!\n\n### Add Documentation Requirements\n\nI usually keep a `doc/requirements.txt` file around so that I don't have to\nhard-code the dependencies necessary to build the documentation anywhere. For\nnow, this may only contain one:\n\n    sphinx\n\nIn the future, you might add others with themes or sphinx extensions.\n\n### Committing to Git\n\nThe entire `doc/` directory tree does not necessarily need to be put into git.\nThe following should suffice:\n\n```bash\ngit add doc/requirements.txt doc/Makefile doc/source/conf.py doc/source/*.rst\ngit commit\n```\n\n### Creating GitHub Pages Branch\n\nGitHub will generate a [GitHub Pages][4] site for any\nrepository that has a `gh-pages` branch. Let's set ours up now:\n\n```bash\ngit checkout --orphan gh-pages\ngit rm -rf .\n```\n\nNow let's add the `.nojekyll` file. This tells GitHub that our content does not\nuse Jekyll for rendering. Finally, commit and push:\n\n```bash\ntouch .nojekyll\ngit add .nojekyll\ngit commit -m 'initial commit'\ngit push origin gh-pages\n```\n\n## Setting up Travis CI\n\nThus far we have only built docs locally. We will now configure [Travis CI][9]\nto build and deploy the docs any time we merge changes to our default branch.\nIt does so by committing the files under `doc/build/html` into the `gh-pages`\nbranch and pushing using your [GitHub Personal Access Token][10].\n\nAll the steps below operate on the `.travis.yml` file in your project\nrepository. It is assumed that you have already setup Travis to build your\nproject, otherwise [start there][12].\n\n### Setting the Version\n\nBecause Python projects usually declare their version in `setup.py`, we want\nSphinx to look there to find the project version so our API docs reflect the\ncorrect value.\n\nIn `doc/source/conf.py`, you likely see this value:\n\n```python\nrelease = '1.2.3'\n```\n\nReplace that line with one that reads the version correctly:\n\n```python\nimport pkg_resources\n\n# Read the project version from setup.py\nrelease = pkg_resources.require(project)[0].version\n```\n\n### Building the Docs\n\nTo start, we need to make sure our build has Sphinx and other doc dependencies\ninstalled, so add a new `install` step:\n\n```yaml\ninstall:\n  - travis_retry pip install -U -r doc/requirements.txt\n  # ...\n```\n\nNext, add an `after_success` step to build the docs:\n\n```yaml\nafter_success:\n  - make -C doc html\n  # ...\n```\n\n### Deploying to GitHub Pages\n\nTravis can [deploy to GitHub Pages][11] on build with the simple addition of a\n`deploy` section:\n\n```yaml\ndeploy:\n  provider: pages\n  skip_cleanup: true\n  github_token: $GITHUB_TOKEN\n  keep_history: true\n  on:\n    branch: main  # the default branch name\n  local_dir: doc/build/html\n```\n\nIf you have not already, turn on [GitHub Pages][4] for your repository using\nthe `gh-pages` branch under *Settings* \u0026rarr; *GitHub Pages*.\n\n### Setting Your GitHub Token\n\n**This step should be taken very carefully!**\n\nFirst, you should have a [token][10] with `repo` scope, so that Travis may\naccess and update your `gh-pages` branch. You will need to copy this token\nshortly.\n\nNavigate to your project settings in Travis. Under the *Environment Variables*\nsection, add a new variable:\n\n| NAME | VALUE | BRANCH | DISPLAY VALUE IN BUILD LOG |\n| ---- | ----- | ------ | -------------------------- |\n| `GITHUB_TOKEN` | *paste your token here* | `main` | **LEAVE UNCHECKED** |\n\nChange `main` if that is not the name of your default branch. Be absolutely sure\nnot to check *Display value in build log* or your API token may be leaked and\nshould be deleted.\n\n### Commit\n\nCommit and push your `.travis.yml` updates, and watch your Travis build logs to\nwatch it in action. If all goes well, your project's GitHub Pages site should be\nnow contain your latest and greatest API documentation.\n\n:tada:\n\n[1]: https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example\n[2]: https://icgood.github.io/continuous-docs/\n[3]: https://docs.python.org/3/library/venv.html\n[4]: https://pages.github.com/\n[6]: https://pypi.python.org/pypi\n[7]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html\n[8]: https://readthedocs.org/\n[9]: https://travis-ci.com/\n[10]: https://github.com/settings/tokens\n[11]: https://docs.travis-ci.com/user/deployment/pages/\n[12]: https://docs.travis-ci.com/user/tutorial/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficgood%2Fcontinuous-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficgood%2Fcontinuous-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficgood%2Fcontinuous-docs/lists"}