Publishing.ReadTheDocs vs GitHub pages. Tutorial-1

Here is comparison for publishing of ReadTheDocs and GitHub: pages project.

Now I faced with some issues of publishing existing project documentation that was created by Sphinx¹
For my personal project on GIT: python_TA_web_api_framework I creted project documentation and generated by Sphinx all necessary data but for some technical reason had no luck to publish it in the web.

Researching existing approaches showed me that there are several platforms for publishing documentation, created mostly in rst² format
Configuration of GitHub: Pages and ReadTheDocs: for same project content is different.

• GitHub: Pages
• ReadTheDocs

In the end after many attempts of building GitHub: Pages and ReadTheDocs: I found test project for playing readthedocs on official readthedocs GitHub:
Assumption of making similar projects on GitHub: Pages and ReadTheDocs: failed. Result below

Source ReadTheDocs projects was

1. https://github.com/ooge0/test-builds
2. https://test-builds.readthedocs.io/

Main configuration files for ReadTheDocs: publishing are below
.readthedocs.yaml

version: 2

build:
  os: ubuntu-24.04
  tools:
    python: latest

sphinx:
  configuration: docs/conf.py

python:
  install:
    - requirements: requirements.txt

requirements.txt

sphinx-autorun
sphinx-rtd-theme>=3.0.0rc2

Another projects for investigation of publishing/deploying conflicts

1. coding-with-kids
   1. GitHub: coding-with-kids
   2. ReadTheDocs: coding-with-kids
2. test-builds
   1. GitHub: test-builds
   2. ReadTheDocs: test-builds
3. readthedocs-demo-app(my project)
   1. GitHub: readthedocs-demo-app
   2. GitHub Pages: readthedocs-demo-app
   3. ReadTheDocs: readthedocs-demo-app. Copied and published based on GitHub: test-builds
4. docs.readthedocs.io
   1. GitHub: docs.readthedocs.io
   2. ReadTheDocs: docs.readthedocs.io
   3. ReadTheDocs: readthedocs-demo-app Copied and published based on GitHub: test-builds
5. jubilant-lamp
   1. GitHub: jubilant-lamp
   2. GitHub pages: jubilant-lamp

References:
1. Post: Sphinx to GitHub Pages via GitHub Actions
2. Post: Генератор документации Sphinx
3. YouTube video: Automate Python Documentation | Use Sphinx + GitHub actions to publish documentation

---

1. 1.Sphinx is a powerful documentation generator that has many features for writing technical documentation. Sphinx is written in Python, and supports documentation written in reStructuredText and Markdown. Official docs on the web site: https://www.sphinx-doc.org ↩
2. 2.reStructuredText (RST, ReST, or reST). reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. The reStructuredText parser is a component of Docutils. reStructuredText is a revision and reinterpretation of the StructuredText and Setext lightweight markup systems. ↩