Directory Structure

Relevant source files

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

• README.md
• conf.py
• index.rst
• Makefile
• _static/css/citheme.css
• _templates/layout.html

This document outlines the directory structure of the CodeIgniter 4 User Guide repository. The repository contains the source files used to generate the official documentation website. The structure is based on the Sphinx documentation generator, which processes reStructuredText (.rst) files, applies configurations, and builds a static HTML site.

The organization of files and directories is designed to separate content from configuration, styling, and build logic. This facilitates an automated build process that transforms the raw documentation source into a polished, web-viewable format. The README.md file clarifies that this is a read-only repository where the user guide is published automatically as part of the framework's release workflow.

Sources: README.md:5-7

High-Level Overview

The root of the repository contains configuration files, build scripts, and directories for content, static assets, and templates. The build process, managed by the Makefile, uses Sphinx to read these sources and generate the final HTML output into the _build directory.

The following diagram illustrates the main components of the repository's structure.

This diagram shows how the Makefile initiates the Sphinx build process, which consumes configuration (conf.py), content (.rst files), static assets (_static/), and templates (_templates/) to produce the final HTML output.

Sources: Makefile:22-23, conf.py, index.rst

Core Components

The repository is organized into several key files and directories that each serve a distinct purpose in the documentation generation pipeline.

Sphinx Configuration (conf.py)

This is the main configuration file for the Sphinx project. It defines project-level metadata, configures Sphinx extensions, and specifies paths for templates and static assets.

Configuration Key	Example Value	Description
project	'CodeIgniter'	The name of the project.
copyright	'2019-2024, CodeIgniter Foundation'	Project copyright information.
html_theme	'sphinx_rtd_theme'	Specifies the theme for the HTML output.
html_static_path	['_static']	A list of paths containing custom static files (CSS, JS).
templates_path	['_templates']	A list of paths containing custom layout templates.
master_doc	'index'	The name of the root document file (index.rst).

These settings control the overall appearance and structure of the generated user guide.

Sources: conf.py:22, 25, 100, 84, 85, 158

Content Source Files

The documentation content is written in reStructuredText (.rst) files. The primary entry point for the content is index.rst, which uses the toctree (Table of Contents Tree) directive to define the high-level structure and order of the documentation sections.

.. toctree::
   :maxdepth: 3
   :caption: Welcome

   intro/index

.. toctree::
   :maxdepth: 2
   :caption: General Topics

   concepts/index
   testing/index

The toctree directive in index.rst links to other .rst files, which are organized into subdirectories corresponding to major topics like intro, installation, tutorial, etc. This creates the hierarchical navigation seen on the final website.

Sources: index.rst:13-26

Static Assets (_static/)

The _static directory, registered in conf.py via the html_static_path setting, contains static files that are copied to the output directory during the build. This includes custom stylesheets, JavaScript files, images, and other assets.

A key file in this directory is _static/css/citheme.css, which contains custom CSS rules to override the default theme and apply CodeIgniter's specific branding and styling to the documentation.

Sources: conf.py:84, _static/css/citheme.css

Layout Templates (_templates/)

The _templates directory is used to override or extend the base theme's templates. This allows for significant customization of the final HTML layout. The path is registered in conf.py via the templates_path setting.

For example, the _templates/layout.html file extends the theme's default layout.html to inject custom elements, such as analytics scripts or modified header/footer blocks, ensuring they appear on every page of the user guide.

Sources: conf.py:85, _templates/layout.html

Build Process

The build process is orchestrated by the Makefile, which provides simple commands to generate the documentation. The primary command is make html.

The flow of the build process is as follows:

1. A user or an automated script runs the make html command.
2. The Makefile executes the sphinx-build command-line tool.
3. sphinx-build reads conf.py for configuration.
4. It starts parsing from the master document, index.rst.
5. It follows the toctree directives to parse all linked .rst content files.
6. It processes the content, applies templates from _templates/, and copies assets from _static/.
7. The final, complete HTML site is written to the _build/html directory.

The following diagram visualizes this workflow.

This diagram shows the sequence of events from command execution to the generation of the final HTML output.

Sources: Makefile:22-23

Summary

The directory structure of the ci4_userguide repository is a well-organized Sphinx project tailored for building the CodeIgniter 4 documentation. It effectively separates configuration (conf.py), content (.rst files), presentation assets (_static, _templates), and build logic (Makefile). This modular structure supports an automated and maintainable workflow for generating the comprehensive user guide from its source files.