Publishing HTML Files

This document provides step-by-step instructions for publishing the HTML documentation of your Python project to:

  1. ReadTheDocs.org

  2. GitHub Pages

Prerequisites

  • Generated HTML files from Sphinx (_build/html directory).

  • A GitHub account.

  • ReadTheDocs account (if using ReadTheDocs.org).

Publishing to ReadTheDocs.org

Step 1: Create a ReadTheDocs Project

  1. Log in to your ReadTheDocs account at https://readthedocs.org/.

  2. Click on + Import a Project.

  3. Select the Connect to GitHub option and authorize ReadTheDocs to access your repositories.

  4. Choose your project repository from the list or add a new repository.

Step 2: Configure ReadTheDocs

  1. Navigate to your project’s settings in ReadTheDocs.

  2. Under the Admin > Advanced Settings section, specify the following: - Python configuration file: docs/conf.py (or the location of your conf.py file). - Documentation type: Sphinx HTML. - Requirements file: requirements.txt (if you have additional Python dependencies).

  3. Save the changes.

Step 3: Trigger a Build

  1. Trigger a build by clicking the Build Version button on the project’s dashboard.

  2. Once the build is complete, your documentation will be live at <project-name>.readthedocs.io.

Step 4: Maintain Updates

  1. Push changes to your GitHub repository.

  2. ReadTheDocs automatically rebuilds the documentation on new commits.

Publishing to GitHub Pages

Step 1: Create a GitHub Repository

  1. Go to https://github.com/.

  2. Click on + New Repository.

  3. Name the repository (e.g., sphinx-dempo-app).

  4. Set the repository as Public.

  5. Click Create Repository.

Step 2: Add HTML Files to the Repository

  1. Navigate to your project’s _build/html directory.

  2. Copy the entire contents of the html directory.

  3. Clone the GitHub repository locally:

git clone https://github.com/<username>/project-docs.git

  1. Paste the HTML files into the cloned repository.

  2. Add, commit, and push the files to GitHub:

Step 3: Enable GitHub Pages

  1. Go to your repository on GitHub.

  2. Navigate to Settings > Pages.

  3. Under Source, select the main branch and / (root) folder.

  4. Click Save.

  5. Your documentation will be live at https://<username>.github.io/project-docs/.

Step 4: Maintain Updates

  1. Update the _build/html directory in your local repository.

  2. Push changes to GitHub:

git add . git commit -m "Update documentation" git push origin main

Tips for Managing Documentation

  • Always generate updated HTML files using Sphinx before publishing.

  • Keep the conf.py and requirements.txt files updated with any project changes.

  • Use meaningful commit messages for documentation updates.

Further Assistance