The CodeIgniter user guide uses Sphinx to manage the documentation and output it to various formats. Pages are written in human-readable ReStructured Text format.
Sphinx requires Python 3.5+, which may already be installed if you are running
OS X or Linux. You can confirm in a Terminal window by executing python
or python3.
python --version
Python 2.7.17
python3 --version
Python 3.6.9
# For Windows using the Python Launcher
py -3 --version
Python 3.8.1If you're not on 3.5+, go ahead and install the latest 3.x version from Python.org. Linux users should use their operating systems' built-in Package Managers to update.
Now that you have Python 3.x up and running, we will be installing pip (The Python Package Installer).
You can check if you have pip installed with pip or pip3.
As you can see pip follow the same naming convention as Python.
Please take note that it should say python 3.x at the very end.
pip --version
pip 9.0.1 from /usr/lib/python2.7/dist-packages (python 2.7)
pip3 --version
pip 9.0.1 from /usr/lib/python3/dist-packages (python 3.6)
# For Windows using the Python Launcher
py -3 -m pip --version
pip 20.0.2 from C:\Users\<username>\AppData\Local\Programs\Python\Python38\lib\site-packages\pip (python 3.8)Installing pip/setuptools/wheel with Linux Package Managers
pip is already installed if you are using Python 3.5+ downloaded from Python.org.
Now we need to install Sphinx and it's dependencies. Choose pip or pip3
depending on operative system. After this step you need to restart your Terminal
window as Python won't find all applications we just installed otherwise.
pip install -r user_guide_src/requirements.txt
pip3 install -r user_guide_src/requirements.txt
# For Windows using the Python Launcher
py -3 -m pip install -r user_guide_src/requirements.txtIt's time to wrap things up and generate the documentation.
cd user_guide_src
make htmlAll of the source files exist under source/ and is where you will add new documentation or modify existing documentation. Just as with code changes, we recommend working from feature branches and making pull requests to the develop branch of this repo.
Obviously, the HTML documentation is what we care most about, as it is the primary documentation that our users encounter. Since revisions to the built files are not of value, they are not under source control. This also allows you to regenerate as necessary if you want to "preview" your work. Generating the HTML is very simple. From the root directory of your user guide repo fork issue the command you used at the end of the installation instructions:
make html
You will see it do a whiz-bang compilation, at which point the fully rendered user guide and images will be in build/html/. After the HTML has been built, each successive build will only rebuild files that have changed, saving considerable time. If for any reason you want to "reset" your build files, simply delete the build folder's contents and rebuild.
Please refer to /contributing/documentation.rst for general guidelines for using Sphinx to document CodeIgniter.