Making the documentation

A brief overview of the files in this repo, and the make-targets in the Makefile, and how it all hangs together to build the final output html files from the initial adoc input files.

TL;DR version: To build the 'regular' documentation site, run make clean; make. To build the documentation site with pico-sdk API docs included, run make clean; make build_doxygen_adoc; make.

Files in the repo

documentation/asciidoc/ all our "regular" asciidoc documentation (referred to as $(ASCIIDOC_DIR) in the Makefile)
documentation/images/ the images shown on the "boxes"
documentation/pico-sdk/ pico-sdk submodule (initially empty) (referred to as $(PICO_SDK_DIR) in the Makefile)
documentation/pico-examples/ pico-examples submodule (initially empty) (referred to as $(PICO_EXAMPLES_DIR) in the Makefile)
jekyll-assets/ various styling stuff used by the jekyll build (referred to as $(JEKYLL_ASSETS_DIR) in the Makefile)
scripts/ various Python build-scripts (referred to as $(SCRIPTS_DIR) in the Makefile)
Makefile top-level Makefile that runs the build

When you clone the repo and run `make`

.DEFAULT_GOAL := html is set in the Makefile, which means that make actually does make html.
1. The html target has the run_ninja target as a prerequisite
  1. The run_ninja target has $(AUTO_NINJABUILD) (i.e. build/autogenerated.ninja) as a prerequisite
    1. build/autogenerated.ninja has $(BUILD_DIR) (i.e. build/) as a prerequisite
      1. So the build/ directory gets created
    2. Then build/autogenerated.ninja gets created
  2. Then ninja gets invoked, which uses build.ninja (which includes build/autogenerated.ninja) to create a whole bunch of files in the build/ directory
2. Then jekyll gets invoked, which uses all the files in the build/ directory to create all the final output files in the $(HTML_DIR) (i.e. documentation/html/) directory

If you run make a second time, then make and ninja will spot that everything is up to date, and only re-run the jekyll stage.

When you run `make clean`

The clean target has the clean_html and clean_doxygen_adoc targets as prerequisites
1. In this case clean_doxygen_adoc doesn't do anything, but clean_html deletes the documentation/html/ directory
Then the build/ directory is deleted

When you run `make build_doxygen_adoc`

The build_doxygen_adoc target has $(ASCIIDOC_DOXYGEN_DIR)/index_doxygen.adoc (i.e. documentation/asciidoc/pico-sdk/index_doxygen.adoc) as a prerequisite
1. documentation/asciidoc/pico-sdk/index_doxygen.adoc has $(DOXYGEN_HTML_DIR) (i.e. build-pico-sdk-docs/docs/doxygen/html/) and $(ASCIIDOC_DOXYGEN_DIR) (i.e. documentation/asciidoc/pico-sdk/) as prerequisites
  1. So the documentation/asciidoc/pico-sdk/ directory gets created
  2. build-pico-sdk-docs/docs/doxygen/html/ has $(ALL_SUBMODULE_CMAKELISTS) (i.e. documentation/pico-sdk/CMakeLists.txt and documentation/pico-examples/CMakeLists.txt) and $(DOXYGEN_PICO_SDK_BUILD_DIR) (i.e. build-pico-sdk-docs/) as prerequisites
    1. So the build-pico-sdk-docs/ directory gets created
    2. documentation/pico-sdk/CMakeLists.txt gets created by initialising the pico-sdk submodule
    3. documentation/pico-examples/CMakeLists.txt gets created by initialising the pico-examples submodule
  3. Then cmake gets invoked for pico-sdk/, which creates build-pico-sdk-docs/Makefile
  4. Then we run the docs target in build-pico-sdk-docs/Makefile which runs doxygen and creates a bunch of HTML files in build-pico-sdk-docs/docs/doxygen/html/ (referred to as $(DOXYGEN_HTML_DIR) in the Makefile)
Then we run the new scripts/transform_doxygen_html.py to convert the HTML files from build-pico-sdk-docs/docs/doxygen/html/ into adoc files in documentation/asciidoc/pico-sdk/

If you run make build_doxygen_adoc a second time, then make will detect that everything is already up to date, and so not do anything.

If we now run make (see the make html description above), it will now find documentation/asciidoc/pico-sdk/ and include that in the "tabs" in the output html files in documentation/html/.

And if we then run a make clean, the presence of documentation/asciidoc/pico-sdk/ will cause the clean_doxygen_adoc target to delete the files in the build/ directory (to prevent things getting into an "invalid state"), and then delete the documentation/asciidoc/pico-sdk/ directory. Note that build-pico-sdk-docs/ (the raw Doxygen output) isn't deleted by make clean, because it's basically "static content" which can take a while to regenerate. To also get rid of build-pico-sdk-docs/ you can either make clean_doxygen_html or make clean_everything (with the latter also deinitialising the submodules).

Makefile targets

Targets which might be useful for getting things to / from a particular state.

make fetch_submodules populates (initialises) the documentation/pico-sdk/ and documentation/pico-examples/ submodule directories
make clean_submodules deinitialises the submodule directories, i.e. is the opposite of fetch_submodules
make build_doxygen_html runs the cmake and make steps required to create the Doxygen HTML files (in build-pico-sdk-docs/docs/doxygen/html/) from the pico-sdk submodule
make clean_doxygen_html deletes the build-pico-sdk-docs/ directory i.e. is the opposite of build_doxygen_html
make build_doxygen_adoc described in an earlier section, converts html files from build-pico-sdk-docs/docs/doxygen/html/ to adoc files in documentation/asciidoc/pico-sdk/
make clean_doxygen_adoc deletes the documentation/asciidoc/pico-sdk/ directory i.e. is the opposite of build_doxygen_adoc
make run_ninja converts adoc files from documentation/asciidoc/ into adoc files in build/
make clean_ninja deletes the files in build/ i.e. is the opposite of run_ninja
make html described in an earlier section, converts adoc files from build/ into html files in documentation/html/. The default target invoked when no explicit target is given.
make clean_html deletes the documentation/html/ directory, i.e. is the opposite of html
make serve_html converts adoc files from build/ into html files in documentation/html/ and then runs a mini webserver so that you can preview the output
make clean runs both of clean_html & clean_doxygen_adoc and also deletes build/
make clean_everything runs all of clean_submodules, clean_doxygen_html and clean i.e. returns your local directory to a fairly pristine state

Note that for day-to-day usage, you'll typically only use the make clean, make, make build_doxygen_adoc and make serve_html commands - the dependencies in the Makefile are all set up so that any necessary intermediate steps are performed automatically.

Bad ASCII-art time:

+---------------+                               
| 'clean' state |--> make build_doxygen_adoc
+---------------+              |
 |    |       ^                V
 |    V       |            +-----------------------------------------+
 |  make    make clean <---| documentation/asciidoc/pico-sdk/ exists |
 |    |       ^            +-----------------------------------------+
 |    |       |                       |        |
 |    |       |                       V        |
 |    V       |                      make      |
 |  +----------------------------+    |        |
 |  | documentation/html/ exists |<---+        |
 |  +----------------------------+             |
 |        |                  ^                 |
 |        V                  |                 |
 +---> make serve_html <-----------------------+
          |                  |
          |                Ctrl-C
          |                  ^
          V                  |
+----------------------------------------------------------+
| documentation/html/ exists and preview webserver running |
+----------------------------------------------------------+