docs: add reference documentations

[JohelEGP]

Resolves #395.

This is a WIP for the reference documentations.
It's in a state that can build the PDF and HTML.
@mpusz Please, use this PR to test #532.

Instructions:

1. Checkout these repositories:
   • https://github.com/JohelEGP/jegp.cmake_modules/.
   • https://github.com/JohelEGP/draft/tree/standardese_sources_base.
   • https://github.com/JohelEGP/cxxdraft-htmlgen/tree/standardese_sources_base.
2. Satisfy the requirements:
   • For the PDF, see the README: https://github.com/cplusplus/draft.
   • For the HTML, see the README: https://github.com/Eelis/cxxdraft-htmlgen.
3. Consider https://github.com/JohelEGP/jegp.cmake_modules/blob/0df2908dfe83b1f95920d2b20d9436b8f8650498/README.md?plain=1#L107-L121.
4. Configure:

   cmake -S docs/reference -B build/docs/reference \
    -DCMAKE_MODULE_PATH="<path to gh:JohelEGP/jegp.cmake_modules>/modules" \
    -DJEGP_STANDARDESE_SOURCES_GIT_REPOSITORY="<path to gh:JohelEGP/draft>" \
    -DJEGP_CXXDRAFT_HTMLGEN_GIT_REPOSITORY="<path to gh:JohelEGP/cxxdraft-htmlgen>"

5. Build as normal.
   For the HTML, you may need to put mathjax-node-cli in PATH.

[mpusz]

I am sorry for coming so late to this.

I got the following error during build:

[11/17] Performing pdf step for 'mp-units_reference_documentations'
FAILED: mp-units_reference_documentations-prefix/src/mp-units_reference_documentations-stamp/Release/mp-units_reference_documentations-pdf /home/mpusz/repos/mp-units/build/docs/reference/mp-units_reference_documentations-prefix/src/mp-units_reference_documentations-stamp/Release/mp-units_reference_documentations-pdf 
cd /home/mpusz/repos/mp-units/build/docs/reference/_jegp_mp-units_reference_documentations_draft_checkout/source && make quiet && ../tools/check-output.sh && /home/mpusz/.local/pip/mpusz/lib/python3.12/site-packages/cmake/data/bin/cmake -E copy std.pdf /home/mpusz/repos/mp-units/build/docs/reference/mp-units.pdf && /home/mpusz/.local/pip/mpusz/lib/python3.12/site-packages/cmake/data/bin/cmake -E touch /home/mpusz/repos/mp-units/build/docs/reference/mp-units_reference_documentations-prefix/src/mp-units_reference_documentations-stamp/Release/mp-units_reference_documentations-pdf
latexmk -pdf std -e '$max_repeat = 1;' -silent || ( rm std.pdf; latexmk -pdf std -e '$max_repeat = 4;' )
Latexmk: Sometimes, the -f option can be used to get latexmk
  to try to force complete processing.
  But normally, you will need to correct the file(s) that caused the
  error, and then rerun latexmk.
  In some cases, it is best to clean out generated files before rerunning
  latexmk after you've corrected the files.
Rc files read:
  /etc/LatexMk
  latexmkrc
Latexmk: Nothing to do for 'std.tex'.
Collected error summary (may duplicate other messages):
  pdflatex: gave an error in previous invocation of latexmk.

rm: cannot remove 'std.pdf': No such file or directory
Latexmk: Sometimes, the -f option can be used to get latexmk
  to try to force complete processing.
  But normally, you will need to correct the file(s) that caused the
  error, and then rerun latexmk.
  In some cases, it is best to clean out generated files before rerunning
  latexmk after you've corrected the files.
Rc files read:
  /etc/LatexMk
  latexmkrc
Latexmk: This is Latexmk, John Collins, 31 Jan. 2024. Version 4.83.
Latexmk: Nothing to do for 'std.tex'.
Latexmk: All targets (std.pdf) are up-to-date
Collected error summary (may duplicate other messages):
  pdflatex: gave an error in previous invocation of latexmk.

make: *** [Makefile:16: quiet] Error 12

[JohelEGP]

Please, share the files /home/mpusz/repos/mp-units/build/docs/reference/_jegp_mp-units_reference_documentations_draft_checkout/source/std.* (including std.tex, in case it's wrong).
One of those outputs should tell what's wrong.

[mpusz]

I thought that the issue is that the scripts try to unconditionally remove std.pdf even if it doesn't exist?

[JohelEGP]

Yeah, it was the std.log.
I have never seen the error.
They all have this form:

! Undefined control sequence.
\customlabel ...tleReference {#2}{\M@currentTitle
                                                  }}\MNR@label {#1}\endgroup...
l.4 \rSec0[scope]{Scope}

The control sequence at the end of the top line
of your error message was never \def'ed. If you have
misspelled it (e.g., `\hobx'), type `I' and the correct
spelling (e.g., `I\hbox'). Otherwise just continue,
and I'll forget about whatever was undefined.

I thought that the issue is that the scripts try to unconditionally remove std.pdf even if it doesn't exist?

That's incidental.

[JohelEGP]

It's important to be able to build the PDF so that any LaTeX error can surface.
Were you also unable to build the PDF in CI?
Perhaps https://github.com/cplusplus/draft's CI setup could serve as a reference.

[mpusz]

Doesn't the HTML version also process all the LaTeX files? I thought I would save time by skipping the PDF generation.

[JohelEGP]

Yes, but it isn't a LaTeX interpreter, so there might be errors.
The sources cxxdraft-htmlgen processes from https://github.com/cplusplus/draft are CI green.

[mpusz]

I sent you a DM on Discord with the logs.

[JohelEGP]

The error when building the PDF goes away with JohelEGP/draft@fa7c7e5.