Build environment for Quickemu project documentation
This is aimed at being a submodule for generating and placing documentation and manual pages.
It consists of a Makefile that calls a script (build_manuals) which generates the README
and the contents of ../docs
Note
Since much of the README has been redirected to the wiki it no longer contains dynamic version-dependant content.
It is likely that it can be removed from this process shortly, if indeed this sub-project has a future at all. Ideally CI/CD can also maintain any wiki content and keeping the man pages in step can be transferred to CI. For now everything is regenerated, but probably only docs need submitting and README checking for local edits and changes
It does this by using a set of parts according to the recipe build in the build_manuals script. To update the 3 manual pages, the markdown sources and
the main project README.md edit or add to the parts, paying
attention to ordering and inclusion of new parts in appropriate recipes, then run make clean;make. This
will generate parts of the documentation by running the software itself to ensure consistency and current alignment.
The Makefile here can also be used (with sudo) to install the man pages and or the software.
The parts list currently consists of:
## Tops and tails
quickemu.1-01-head.md
quickemu_conf.1-00-hdr.md
quickemu_conf.1-05-footer.md
quickget.1-00-header.md
quickget.1-09-footer.md
README-00-hdr.md
quickemu.1-30-Footers.md
# The Seed parts for generation with `cog`
XXquickemu.1-08-OtherOperatingSystems01.md
XXquickemu.1-14-AllquickemuOptions-02coggged.md
# The static parts
quickemu.1-02-options.md
quickemu.1-03-examples.md
quickemu.1-04-intro.md
quickemu.1-05-features01.md
quickemu.1-06a-GUI.md
quickemu.1-06-requirements.md
quickemu.1-07-Ubuntus00.md
quickemu.1-07-Ubuntus01.md
quickemu.1-08-OtherOperatingSystems01.md
quickemu.1-09-othermanualguests.md
quickemu.1-10-macOSguests.md
quickemu.1-11-Windowsguests.md
quickemu.1-15-UsageNotes.md
quickemu.1-20-References.md
README-00-hdr.md
README-01-Intro.md
README-02-Features.md
README-03-Quickstart.md
README-04-Documentation.md
README-05-Contribution.md
README-06-Install.md
README-135-accessibility.md
README-135-confoptions.md
## No longer / not yet in use
quickemu_conf.1-01-spiceheadless.md
quickemu.1-13-OtherGuests01.md
README-06-Install.md
README-135-accessibility.md
## README list
README-01-Intro.md
README-02-Features.md
README-03-Quickstart.md
README-04-Documentation.md
README-05-Contribution.md
## quickget list
quickget.1-00-header.md
quickemu.1-07-Ubuntus00.md
quickemu.1-07-Ubuntus01.md
quickemu.1-07-Ubuntus02-generated.md
quickemu.1-08-OtherOperatingSystems01.md
quickemu.1-08-OtherOperatingSystems02-generated.md
quickemu.1-09-othermanualguests.md
quickemu.1-10-macOSguests.md
quickemu.1-11-Windowsguests.md
quickget.1-09-footer.md
## quickemu list
quickemu.1-01-head.md
quickemu.1-02-options.md
quickemu.1-03-examples.md
quickemu.1-04-intro.md
quickemu.1-05-features01.md
quickemu.1-06-requirements.md
quickemu.1-06a-GUI.md
quickemu.1-07-Ubuntus00.md
quickemu.1-07-Ubuntus01.md
quickemu.1-07-Ubuntus02-generated.md
quickemu.1-08-OtherOperatingSystems01.md
quickemu.1-08-OtherOperatingSystems02-generated.md
quickemu.1-09-othermanualguests.md
quickemu.1-10-macOSguests.md
quickemu.1-11-Windowsguests.md
quickemu.1-14-AllquickemuOptions-02coggged.md
quickemu.1-15-UsageNotes.md
quickemu.1-20-References.md
quickemu.1-30-Footers.md
## quickemu_conf list
quickemu_conf.1-00-hdr.md
README-135-confoptions.md
quickemu_conf.1-05-footer.md
The process requires
- a recent version of
pandoc- ( which you can obtain with
deb-get install pandoc- if you havedeb-get)
- ( which you can obtain with
cog(install withpip3 install cogapp)
You will need this submodule checked out appropriately under a clone of the quickemu repo. The build uses ../quickemu for the most part, so will build docs
based on the the position in this submodule but consistent with the version of software in the parent directory. cog updates are designed to happen within the
parent repo (so they can happen in GitHub too ), so the Makefile will enforce a symlink to appear here pointing to ../quickemu
The general flow of the build is:
# in the `quickemu` clone
git pull -r --no-recurse-submodules # or checkout <branch> ...
cd build_docs
# this will be detatched at the commit in the parent
# usually this is not what you want but is needed for repeatability
# Generally you will want to
git checkout main # or relevant branch or
make clean
make
This should result in a perfect and consistent set of markdown docs and man pages in ../docs/ and also the matching ../README.md
It is essential to check and preview the generated assets before
committing them or installing them since mistakes are easy, helpful software sometimes is too helpful, and pandoc, cog and github markdown sometimes choose
to fight rather than cooperate so small edits or patches may be needed to achieve satisfactory outcomes.
Once satisfied, you can optionally install the man pages so generated (and even the versions of the executables ) with
sudo make install_{docs|bins}
or
sudo make install
and/or if the parent is checked out on a branch for submiting or updating a PR upstream, then
cd ..
git add docs/quick*
## optionally now also
#git add README.md
git commit
git push