{"id":15533237,"url":"https://github.com/maltfield/rtd-github-pages","last_synced_at":"2025-04-15T11:17:18.564Z","repository":{"id":39092572,"uuid":"280336689","full_name":"maltfield/rtd-github-pages","owner":"maltfield","description":"Fork-ready base for your project's documentation using Sphinx + Read the Docs on GitHub Pages ","archived":false,"fork":false,"pushed_at":"2023-10-14T13:33:25.000Z","size":6034,"stargazers_count":50,"open_issues_count":5,"forks_count":85,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-15T11:16:58.205Z","etag":null,"topics":["continuous-documentation","github-actions","github-pages","python","read-the-docs","rtd","sphinx"],"latest_commit_sha":null,"homepage":"https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maltfield.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":"2020-07-17T05:40:05.000Z","updated_at":"2024-09-06T22:01:27.000Z","dependencies_parsed_at":"2023-10-15T14:20:56.355Z","dependency_job_id":"8f232d37-1e63-4530-846c-244af93645ba","html_url":"https://github.com/maltfield/rtd-github-pages","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/maltfield%2Frtd-github-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maltfield%2Frtd-github-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maltfield%2Frtd-github-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maltfield%2Frtd-github-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maltfield","download_url":"https://codeload.github.com/maltfield/rtd-github-pages/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249058386,"owners_count":21205911,"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":["continuous-documentation","github-actions","github-pages","python","read-the-docs","rtd","sphinx"],"created_at":"2024-10-02T11:35:00.629Z","updated_at":"2025-04-15T11:17:18.535Z","avatar_url":"https://github.com/maltfield.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![docs_pages_workflow](https://github.com/maltfield/rtd-github-pages/workflows/docs_pages_workflow/badge.svg?branch=master)\n\n# Continuous Documentation: Hosting Read the Docs on GitHub Pages\n\nThis repo is a fork-ready base for your project's documentation. It lets you host a sphinx-generated site (with the Read the Docs theme) on GitHub Pages using GitHub Actions.\n\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/\"\u003e\u003cimg src=\"docs/_static/sphinx-rtd-github-pages-1_featuredImage1.jpg?raw=true\" alt=\"Continuous Documentation with Read the Docs on GitHub Pages using GitHub Actions\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nFor more information, see this article:\n\n * https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/\n\n# How to use this repo\n\n1. Fork this repo\n1. On your forked repo, go to the \"Actions\" tab and click \"I understand my workflows, go ahead and enable them\" to enable GitHub workflows\n1. On your forked repo, go to the \"Settings\" tab. Under \"GitHub Pages\" choose 'gh-pages branch' under \"Source\"\n1. Make a small change to [docs/index.rst](/docs/index.rst)\n1. `git commit` and `git push` something to trigger your site to be built\n\nEvery time you push to github.com on master, github will automatically spin up a container in their cloud to update your documentation.\n\nAfter you begin to edit the contents of the site, you'll probably also want to customize  the following files:\n\n1. [docs/conf.py](/docs/conf.py)\n1. The python files in [src/](/src/)\n1. Other `.rst` files in [docs/](/docs) as needed\n\nFor more details on how this works, see [Continuous Documentation: Hosting Read the Docs on GitHub Pages](https://tech.michaelaltfield.net/2020/07/18/sphinx-rtd-github-pages-1/)\n\n# Demo\n\nThe GitHub-Pages-hosted \"Hello World\" example site built by this repo can be viewed here:\n\n * https://maltfield.github.io/rtd-github-pages/\n\n## In the wild\n\nThe following Githb-Pages-hosted Read the Docs sites have been created by cloning this repo:\n\n * [BusKill Docs](https://docs.buskill.in/buskill-app/en/stable/) ([repo](https://github.com/BusKill/buskill-app/tree/master/docs))\n * [Python Bootcamp for Science](https://vienneae.github.io/rtd-github-pages/en/master/index.html) ([repo](https://github.com/vienneae/rtd-github-pages/tree/master/docs))\n * [Py4Web Docs](https://nicozanf.github.io/py4web-doc/) ([repo](https://github.com/nicozanf/py4web-doc/tree/master/docs))\n * [Hercules Docs](https://fovea1959.github.io/herc-docs-demo/en/master/index.html) ([repo](https://github.com/fovea1959/herc-docs-demo/))\n\n# Local Iteration\n\nAs shown above, you can simply push your changes to GitHub to update your sphinx documentation website.\n\nHowever, you can also build the site locally on your computer for faster iteration.\n\n## Linux\n\nTo build the site on Debian Linux, first download some dependencies\n\n```\nsudo apt-get update\nsudo apt-get -y install git firefox-esr python3-git python3-sphinx python3-sphinx-rtd-theme\n```\n\nChange into the `docs` directory of this repo and build the sphinx site with `make`\n\n```\ncd rtd-github-pages/docs/\nmake clean\nmake html\n```\n\nYou can view the site (built into the `_build/html/` directory) using firefox\n\n```\nfirefox-esr _build/html/index.html\n```\n\n# License\n\nThe contents of this repo are dual-licensed. All code is GPLv3 and all other content is CC-BY-SA.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaltfield%2Frtd-github-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaltfield%2Frtd-github-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaltfield%2Frtd-github-pages/lists"}