ghpages.rst

Generating the User Guide

The intent is, eventually, for the in-progress user guide to be automatically generated as part of a PR merge. This writeup explains how it can be done manually in the meantime.

The user guide takes advantage of Github pages, where the "gh-pages" branch of a repo, containing HTML only, is accessible through github.io.

Setup for Repo Maintainers

You already have the repo cloned into CodeIgniter4 in a projects folder. Create another folder at the same level as this, CodeIgniter4-guide. Clone the CodeIgniter4 repo again, into CodeIgniter4-guide/html.

Inside the html folder, git checkout gh-pages. All you should see is the generated HTML for the user guide.

Re-generating the User Guide

In the user_guide_src folder, you generate a conventional user guide, for testing, using the command:

make html

An additional target has been configured, which will generate the same HTML but inside the html folder of the second repo clone:

make ghpages

After making this target, update the online user guide by switching to the CodeIgniter4-guide/html folder, and then:

git add .
git commit -S -m "Suitable comment"
git push origin gh-pages

Process

There should be only one maintainer doing this, to avoid collisions. The user guide would get regenerated whenever there is a PR merge that affects it.

Note: You might have to delete the user_guide_src/doctree folder before making the gh-pages version of the guide, to make sure that the TOC is properly rebuilt, especially if you are rebuilding the html target a number of times.