From 6b5a5ac400483e320d57c037f534b57504959b05 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 17 Feb 2025 13:03:06 -0700 Subject: Update doc development overview [ci skip] Includes updates to the diagram that shows the doc flow (although it could still be improved. I'm not a diagramming expert so settling for what I could accomplish) Signed-off-by: Mats Wichmann --- doc/images/overview.graphml | 76 ++++++++++++++++++++++++-------------------- doc/images/overview.png | Bin 36232 -> 24170 bytes doc/overview.rst | 54 +++++++++++++++++++------------ 3 files changed, 75 insertions(+), 55 deletions(-) diff --git a/doc/images/overview.graphml b/doc/images/overview.graphml index 74f80d7..63ecd36 100644 --- a/doc/images/overview.graphml +++ b/doc/images/overview.graphml @@ -1,39 +1,39 @@ - - - + + + - + - + - + - User's view + User's view - + - Folder 1 + Folder 1 @@ -46,10 +46,11 @@ - + - XML files (src/user/man/...) + XML files (user guide, +manpage, source tree) @@ -63,10 +64,10 @@ - + - XML validation + XML validation @@ -83,7 +84,8 @@ - Writer + Writer + @@ -102,11 +104,10 @@ - + - Creating entity lists - + Creating entity lists @@ -120,11 +121,11 @@ - + - Check that example -names are unique + Check that example + names are unique @@ -141,7 +142,7 @@ names are unique - Create example outputs + Create example outputs @@ -158,8 +159,8 @@ names are unique - Resolve XIncludes for text -and examples + Resolve XIncludes for + text and examples @@ -173,10 +174,10 @@ and examples - + - Create HTML, PDF, Man + Create HTML, PDF, Man @@ -190,10 +191,10 @@ and examples - + - Install in proper place + Install in proper place for packaging @@ -208,11 +209,11 @@ for packaging - + - Create API doc -(Epydoc) + Create API doc +(Sphinx) @@ -229,7 +230,8 @@ for packaging - get validated + get validated + @@ -267,7 +269,9 @@ for packaging - + + + @@ -300,7 +304,8 @@ for packaging - switching to Docbook + switching to Docbook + @@ -333,13 +338,14 @@ for packaging - edits/creates + edits/creates + - + <?xml version="1.0" encoding="utf-8"?> <!-- Generator: Adobe Illustrator 15.0.2, SVG Export Plug-In . SVG Version: 6.00 Build 0) --> diff --git a/doc/images/overview.png b/doc/images/overview.png index f1189c9..b83e955 100644 Binary files a/doc/images/overview.png and b/doc/images/overview.png differ diff --git a/doc/overview.rst b/doc/overview.rst index 79b407a..8a1d56a 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -6,19 +6,25 @@ SCons Documentation Toolchain Introduction ============ -This text tries to give an overview of the current SCons documentation -toolchain. As a prospective doc editor, you should be able to quickly +This is an overview of the current SCons documentation toolchain. +As a prospective doc editor, you should be able to quickly understand the basic concepts (if not, please let the project know how it falls short). It is also a reference for core developers and the release team. .. image:: images/overview.png -The diagram above roughly shows the steps that we currently need for -creating all the MAN pages, User manuals and reference documents. You -may think: "Geeez, that looks so complicated. Why can't they simply -convert XML files to PDF with Docbook, or use reST?" Please be patient, -and continue reading. Things will get a little clearer soon. +The diagram above roughly shows the steps that we currently use. +Note there are two separate sets of documentation maintained with +the project code itself: the reference manual and user guide, +which have xml source files; and the docstrings in the Python code, +from which the API documentation is generated. Most of the time +when we talk about "SCons Documentation" we mean the former, +as that's what is intended for end-user consumption. + +If you look at the diagram, it looks a bit complicated. after +reading this overview, it will be clear what is actually happening, +and why we need all these steps. Our toolchain doesn't only produce HTML and PDF files that are nice to look at, it also performs a lot of processing under the covers. We @@ -30,31 +36,36 @@ So let's start right at the top... Writer's view ============= -SCons documentation is written in Docbook (the xml variant). -The toolchain is set up so that a writer has a restricted view of the +SCons documentation is written in Docbook XML. +The toolchain is set up so a writer has a restricted view of the whole "document processing thingy". All you should need to be concerned with is to edit existing text or write new sections and paragraphs. Sometimes even a completely new chapter has to be added. The hope is that you can fire up your XML editor of choice and type away. -XML is easy to get wrong, so you need to case about +XML is easy to get wrong, so you need to care about validating the XML files -against our special "SCons Docbook DTD/XSD". You can run the -special script +against our special "SCons Docbook DTD/XSD". +If you're not using an XML editor, validate by :: python bin/docs-validate.py -from the top source folder to validate. If you are able to use -an XML editor, many of the potential problems are avoided - -the most common error is not matching tag opening and closing +from the top source folder. If you are able to use +an XML editor, many of the potential problems are avoided, +as it will complain real-time. +The most common error is not matching tag opening and closing (for example ``foo`` is an easy typing error to make, as is starting a ````, typing text, and not adding the -closing ````). XML editors make it much harder to make -those errors, which minor though they seem, will completely -break the document build. +closing ````, as is mistyping one of the two +tag markers). XML editors make it much harder to make +those errors, which, minor though they seem, will completely +break the document build. Unfortunately, the validation tools +(which rely on the capabilities of the XML parser in use) +are not that hard to fool, so you may get errors which are +not that easy to deciper. There isn't much we can do about that. Everything's looking okay, all validation passed? Good, then simply commits your new work, and create a pull request on Github. That's it! @@ -71,6 +82,8 @@ the actual XML files. You can call from within the directory, and have the MAN pages or HTML created...even PDF, if you have a renderer installed (``fop``, ``xep`` or ``jw``). +At least ``fop`` doesn't like everything the docbook/xml chain +produces and will spew a lot of errors, which we *think* are harmless. Validation ========== @@ -149,7 +162,7 @@ By calling the script you can recreate the lists of entities (``*.mod``) in the ``generated`` folder. At the same time, this will generate the matching ``*.gen`` -files, which list the full description of all the Builders, Tools, +files, which hold the full descriptions of all the Builders, Tools, Functions and CVars for the MAN page and the User Guide's appendix. Thus, you want to regenerate when there's a change to any of those four special elements, or an added or deleted element. @@ -217,7 +230,7 @@ For example, when documenting a Tool in ``SCons/Tool/newtool.xml`` using the ```` tag, and noting that the tool ```` or ```` certain construction variables, -those construction variables can be documented +those construction variables can be documented right there as well using ```` tags. When processed with ``SConsDoc`` module, this will generate xml from the @@ -279,6 +292,7 @@ part so that the version control system can show any unexpected changes in the outputs after editing the docs: :: + git diff doc/generated/examples Some of the changes in example text are phony: despite best -- cgit v0.12