Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• .readthedocs.yml
• conf.py
• composer.json
• requirements.txt
• Makefile

This guide outlines the deployment process for the CodeIgniter 4 User Guide. In the context of this project, "deployment" refers to the process of building the static HTML documentation from its reStructuredText (.rst) source files. The repository is designed for automated builds, primarily through the Read the Docs platform, but also supports local builds for development and verification purposes.

The core of the build process relies on the Sphinx documentation generator, configured via conf.py, with dependencies managed by both Python's pip and PHP's composer. The README.md file clarifies that this repository is a read-only publication target, with the build process being a key part of its lifecycle.

Sources: README.md, .readthedocs.yml

Build Environment Setup

To build the documentation, a specific environment with Python and PHP dependencies is required. These are defined in requirements.txt and composer.json, respectively.

Python Dependencies

The build process is orchestrated by Sphinx, a Python tool. All required Python packages are listed in requirements.txt. The .readthedocs.yml file specifies the Python version and the use of this requirements file for setting up the build environment.

The following table lists some of the key Python dependencies:

Package	Description
sphinx	The core documentation generator.
sphinx-rtd-theme	The "Read the Docs" theme used for the HTML output.
docutils	A toolkit for processing plaintext documentation.
pygments	A generic syntax highlighter used for code blocks.

Sources: requirements.txt, .readthedocs.yml:8-11

PHP Dependencies

PHP dependencies are managed via Composer and defined in composer.json. These are necessary for custom scripts or tools that might be used during the documentation build, such as the "post-install-cmd" script which runs a pre-build PHP script.

{
    "name": "codeigniter4/userguide",
    "type": "project",
    "description": "CodeIgniter4 user guide",
    "homepage": "https://codeigniter.com",
    "license": "MIT",
    "require": {
        "php": ">=7.4",
        "ext-intl": "*",
        "ext-json": "*"
    },
    "scripts": {
        "post-install-cmd": [
            "php pre-build.php"
        ]
    }
}

Sources: composer.json:1-19

Build Process

The documentation can be built automatically on a CI/CD platform like Read the Docs or manually on a local machine.

Automated Build on Read the Docs

The .readthedocs.yml file orchestrates the entire build process on the Read the Docs platform. It defines the build image, Python version, and the sequence of commands to execute.

This diagram illustrates the automated build flow as defined in the configuration file.

The configuration specifies the OS, tools, and build steps:

Configuration Key	Value	Description
version	2	The configuration file format version.
build.os	ubuntu-22.04	The operating system for the build environment.
build.tools.python	3.11	The Python version to use.
sphinx.configuration	conf.py	Path to the Sphinx configuration file.
python.install	requirements.txt	Specifies the Python dependencies file.
build.jobs.post_install	composer install	Command to run after installing base dependencies.

Sources: .readthedocs.yml:2-16

Local Build using Makefile

For local development, the Makefile provides a set of convenient commands to manage the build process. The primary command is make html, which triggers the Sphinx build.

This diagram shows the local build workflow initiated by a developer.

The Makefile simplifies common tasks:

Command	Action
make html	Builds the static HTML documentation in the build/html directory.
make clean	Removes the build directory and all generated files.
make livehtml	Starts a local server with live-reloading to preview changes.

Sources: Makefile

Sphinx Configuration

The conf.py file is the central configuration for the Sphinx build. It defines project metadata, extensions, and HTML theme options.

Key Configuration Variables

The following variables in conf.py are crucial for defining the output of the user guide.

Variable	Description
project	The name of the project, e.g., 'CodeIgniter'.
copyright	The copyright notice string.
version	The major version number, used for display.
release	The full version string, including alpha/beta/rc tags.
extensions	A list of Sphinx extensions to enable (e.g., sphinx.ext.autodoc).
html_theme	The theme for the HTML output, set to sphinx_rtd_theme.
html_logo	Path to the logo image file displayed in the sidebar.
html_context	A dictionary of values passed to the template engine, used for GitHub links.
highlight_language	The default language for syntax highlighting, set to php.

Sources: conf.py

Summary

The deployment of the CodeIgniter 4 User Guide is a well-defined process centered around the Sphinx documentation generator. It is fully automated for publication on Read the Docs, with configuration managed in .readthedocs.yml. For local development, a Makefile provides simple commands to build and preview the documentation. The entire system relies on a combination of Python and PHP dependencies, ensuring that all necessary tools and scripts are available for a successful build.

Sources: README.md, .readthedocs.yml, Makefile