Merge pull request #194 from jim-parry/guide/hack

User guide rebuilding

user_guide_src/ghpages.rst

@@ -0,0 +1,52 @@
+#########################
+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
+<https://bcit-ci.github.io/CodeIgniter4>`_.
+
+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.