Follow-up from "WIP: Convert documentation from docbook to sphinx-doc syntax"
The following discussion from !1761 (merged) should be addressed:
-
@each started a discussion: (+1 comment) - I notice
make doc
doesn't generate PDFs, I had tomake pdf
explicitly. -
make all
apparently includes amake doc
step, now, which seems unnecessary to me. - Running
make all
in a clean directory always seems to fail while building doc the first time, though it always seems to succeed on the second attempt. I haven't had time to dig in to what's causing this. - Is the directory name
_build
a requirement of sphinx? It's an admittedly minor quibble, but I wish the HTML still appeared in doc/arm, or at most one level down instead of two. - Why do we have both
_build/html
and_build/dirhtml
? -
make clean
andmake docclean
both fail to clean up generated documentation. - The files in doc/arm/man appear to be generated from RST source, but are checked into git, whereas elsewhere you seem to have removed all the generated documentation; what's the purpose of having these checked in?
- Chapter numbering is very weird - what used to be section 3.4 on plugins is now a very short chapter by itself, and many the sections of chapter 4 seem to have been split out into separate chapters too. The result is what used to be 8 chapters and 4 appendices is now 19 chapters. The appendices are no longer at the end.
- (Not a regression, but it's also really weird to have the advanced DNS features turn up in the ARM before the basic configuration directions. We should reorder the chapters.)
Looking over the generated PDF's for the ARM and the release notes:
- The ISC logo has become kind of tiny now.
- Many of the grammars in the ARM display weirdly. They're enclosed in boxes but they spill out past the margins, and there are XML tags in them. The ones in the named.conf man page in chapter 19 are fine, but in the earlier parts of the ARM they're broken. I'm guessing this is a bug in the rst-zoneopt.pl and/or rst-grammars.pl scripts.
- Tables that fill a whole page look weird (see pages 50, 60 and 125 for examples). I don't think this is a regression, though.
- Odd formatting in a table on page 61 as well.
- Option definitions should probably have a line break after the option name. (See page 77 for examples of what I mean - the first line of the text describing the option flows right after the option name, and it looks to me like it should start on the line below.)
- The table defining rrset-order values is positioned incorrectly on page 93.
- Tables spill over the right margins on pages 127 and 135.
- Table appears to incorrectly contain another table on page 132.
- Table formatting error on page 137.
Looking over the generated HTML:
- The formatting here is generally very nice!
- The same problem also applies here with grammars - XML tags are visible.
- RFC references in chapter 17 are formatted oddly, with author names showing up as "VixieP" and "AndrewsM", commas missing.
- I notice