Hi, Here are fixes for the Sphinx processing warnings reported with `make htmldocs' for the description of the Oxford Semiconductor PCIe (Tornado) 950 driver recently added. I have split them into two parts so that they can be considered separately. First, Documentation/tty/ has been moved to driver-api, which I find not suitable for user documentation, so I have now moved the description to Documentation/misc-devices/. I found no better place, but I can update the change again if you have a better suggestion. Second, actual warnings have been removed. I have corrected quoting for symbol/parameter references, quoted tables and rewritten bibligraphy in Sphinx's style. Third, the document has now been wired into the misc-devices document, so that it is not an orphan page in the HTML format anymore and it is also included in PDF documentation. I have verified the result and considered it visually sound with output produced by `make htmldocs' and `make pdfdocs'. For the latter command however I need to note that several other documents in our Documentation/ tree suffer from a problem that causes `make pdfdocs' to fail (and the failure cannot be worked around with make's `-k -i' options, i.e. no output is ever produced), e.g.: Markup is unsupported in LaTeX: filesystems/9p:: nested tables are not yet implemented. and similarly for: filesystems/erofs, filesystems/f2fs, filesystems/ntfs, networking/device_drivers/ethernet/dlink/dl2k, scsi/arcmsr_spec, scsi/g_NCR5380, scsi/ncr53c8xx, and scsi/sym53c8xx_2. I don't know if it is a known problem, possibly addressed in a newer version of tools, so I've thought it might be worth reporting. I have worked around the problem by removing the offending files, which let `make pdfdocs' proceed to completion. I have spotted another problem there then in that the table of contents is only generated in the output file produced upon the second or subsequent invocations of `make pdfdocs'. Similarly bibligraphy links (but not the list itself). Upon the first run of `make pdfdocs' on a clean Documentation/ tree the Contents section only has its heading and bibligraphy links are dead with `[?]' showing (the section is correctly populated however). It's not clear to me if this is a bug in the tools used or something wrong with our Makefile system, so again I've thought it might be worth reporting. NB XeTeX, Version 3.14159265-2.6-0.99999 (TeX Live 2019/dev/Debian) and Sphinx 1.8.4 here. The issues are not directly related to the changes proposed here though, so please apply them. Maciej
Hi Maciej, On Fri, 13 May 2022 23:41:57 +0100 (BST), Maciej W. Rozycki wrote: > Hi, > [...] > > For the latter command however I need to note that several other > documents in our Documentation/ tree suffer from a problem that causes > `make pdfdocs' to fail (and the failure cannot be worked around with > make's `-k -i' options, i.e. no output is ever produced), e.g.: > > Markup is unsupported in LaTeX: > filesystems/9p:: nested tables are not yet implemented. > > and similarly for: filesystems/erofs, filesystems/f2fs, filesystems/ntfs, > networking/device_drivers/ethernet/dlink/dl2k, scsi/arcmsr_spec, > scsi/g_NCR5380, scsi/ncr53c8xx, and scsi/sym53c8xx_2. I don't know if it > is a known problem, possibly addressed in a newer version of tools, so > I've thought it might be worth reporting. > [...] > > NB XeTeX, Version 3.14159265-2.6-0.99999 (TeX Live 2019/dev/Debian) and > Sphinx 1.8.4 here. As mentioned in the section titled "PDF and LaTeX builds" in Documentation/doc-guide/sphinx.rst, "make pdfdocs" requires Sphinx 2.4 or later. Another hint for you. You can say "make SPHINXDIRS=<sub dir> htmldocs pdfdocs" to test-build docs under Documentation/<sub dir>/. You might see false warnings of "WARNING: undefined label: ..." which you wouldn't see in full builds, though. Hope this helps. I see there is no mention of the SPHINXDIRS make variable in the doc-guide. I'll see it can be explained somewhere in sphinx.rst. Thanks, Akira > > The issues are not directly related to the changes proposed here though, > so please apply them. > > Maciej
On Sun, 15 May 2022, Akira Yokosawa wrote: > > NB XeTeX, Version 3.14159265-2.6-0.99999 (TeX Live 2019/dev/Debian) and > > Sphinx 1.8.4 here. > > As mentioned in the section titled "PDF and LaTeX builds" in > Documentation/doc-guide/sphinx.rst, "make pdfdocs" requires Sphinx 2.4 or > later. Ack, noted. Note however that Documentation/Changes says: Sphinx\ [#f1]_ 1.7 sphinx-build --version ====================== =============== ======================================== .. [#f1] Sphinx is needed only to build the Kernel documentation Perhaps the additional requirement could be mentioned in the footnote? [Also this is a production system and 1.8.4 is the only version available in the distribution it has installed, so I may not be able to upgrade for the foreseeable future anyway.] > You can say "make SPHINXDIRS=<sub dir> htmldocs pdfdocs" to > test-build docs under Documentation/<sub dir>/. > You might see false warnings of "WARNING: undefined label: ..." > which you wouldn't see in full builds, though. > > Hope this helps. Sure, thanks a lot! Maciej
© 2016 - 2024 Red Hat, Inc.