Hi On Thu, Feb 14, 2019 at 12:30 PM Peter Maydell <peter.mayd...@linaro.org> wrote: > > Ping! Thanks to Alex for doing low-level review of this patchset.
Overall, looks good to me too. Minor nit: configure doesn't check presence of sphinx-build, and on my fc29, it's sphinx-build-3 :) CI files will probably need to be updated. > I'm particularly interested in high-level review: > * is this the right way to be going? > * if we committed this and then did a release with the > docs as they are like this, would that be ok? Certainly, it can improve over time imho. > * what's the most important next step after this? > For me the next steps are: - merge your series! :) - integrate the texi doc somehow (apparently Paolo had some solution), or convert the texi doc to rst (modiy texi2any to do that?) - have the docs hosted on www.qemu.org, with some stability (ideally, we could share links to a specific doc, say a QMP command or an internal API, that would remain stable). I wonder why Daniel qemu-web patches aren't yet merged. I remember some questions regarding doc import and automation. There will be a similar problem with sphinx doc. (gitlab makes this fairly easy with CI artifcats, fwiw ;-) - convert more of our doc to rst - add kerneldoc - improve the style, for consistency with qemu.org style > thanks > -- PMM > > On Fri, 1 Feb 2019 at 14:50, Peter Maydell <peter.mayd...@linaro.org> wrote: > > > > This patchset enables building and installing the various rST > > docs we have started to accumulate in our docs/ directory. > > It does this using Sphinx (which is the docs tooling that the > > Linux kernel uses). The series is not trying to take us in one > > giant leap to a brave new Sphinx-powered world -- it is simply > > setting up a framework so that we are at least building and > > shipping these documents and can gradually migrate other parts > > of our documentation to it. > > > > The approach I've used here is that we will have multiple "manuals", > > as proposed by Paolo here: > > https://wiki.qemu.org/Features/Documentation > > For the moment I've only created 'interop' and 'devel' as we don't > > yet have any rST files for 'user', 'system' or 'specs'. > > > > One slightly awkward mismatch between how Sphinx naturally wants > > to work and our requirements is that when Sphinx generates a > > documentation set all in one go it creates hyperlinks between > > all the docs, they all appear in a single top level table of > > contents, and so on. But for QEMU's docs we don't want to > > ship the "devel" manual to end-users. I've taken an approach > > suggested to me on sphinx-users > > (https://www.mail-archive.com/sphinx-users@googlegroups.com/msg03224.html) > > where we run Sphinx once per manual, and treat them as > > entirely separate documents. The config/tooling in this patchset > > also supports building everything in a single run, for compatibility > > with third-party docs sites like readthedocs.org. > > > > To see the results: > > > > What you get in the docs/ subdir of your build directory > > when you do a local build: > > http://people.linaro.org/~peter.maydell/build-dir-docs/ > > (follow the links to 'devel' and 'interop' for the two manuals) > > > > What we'll ship in 'make install' in /usr/local/share/doc/qemu/ > > http://people.linaro.org/~peter.maydell/installed-docs/ > > (should be same as the build dir except we don't ship 'devel') > > > > What you get with a standalone single-run docs build: > > http://people.linaro.org/~peter.maydell/standalone-docs/index.html > > > > These use the default 'alabaster' theme from Sphinx. I > > also experimented with the 'read_the_docs' theme, which I > > do think looks nicer. Unfortunately it also requires the > > docs we install to include about 3MB of TrueType font files > > per manual, which is awkward licensing-wise as the TTFs are > > under the Open Font License and it's not completely clear to > > me that it's OK to ship those to use with a doc file that is > > GPLed. Alabaster doesn't ship fonts, which sidesteps both > > those problems. > > > > Other notes: > > * this does not build the two .rst files that are directly > > in docs/ (cpu-hotplug.rst and pr-manager.rst) -- we should > > move these to whichever of the five manuals is the best place > > * I do have some prototype patches which integrate the kernel's > > kerneldoc Sphinx extension to parse doc comments in source > > code. I haven't included them here because I think the 'devel' > > manual is the lowest priority of the five. They might be > > useful if we want to try things like building documentation > > of supported machine models from in-code comments/etc, though. > > * as noted in a previous email thread, the configure changes > > now mean that building docs depends on build-sphinx being > > available, so this is a new build-dep for --enable-docs. > > > > thanks > > -- PMM > > > > Peter Maydell (11): > > docs/cpu-hotplug.rst: Fix rST markup issues > > docs: Convert memory.txt to rst format > > docs: Commit initial files from sphinx-quickstart > > docs/conf.py: Disable unused _static directory > > docs/conf.py: Configure the 'alabaster' theme > > docs/conf.py: Don't include rST sources in HTML build > > docs/conf.py: Disable option warnings > > Separate conf.py for each manual we want > > Makefile, configure: Support building rST documentation > > Makefile: Abstract out "identify the pkgversion" code > > docs/conf.py: Don't hard-code QEMU version > > > > configure | 4 +- > > Makefile | 78 +++++++--- > > docs/conf.py | 215 ++++++++++++++++++++++++++ > > docs/cpu-hotplug.rst | 2 +- > > docs/devel/conf.py | 15 ++ > > docs/devel/index.rst | 21 +++ > > docs/devel/{memory.txt => memory.rst} | 128 ++++++++------- > > docs/index.rst | 15 ++ > > docs/interop/conf.py | 15 ++ > > docs/interop/index.rst | 18 +++ > > 10 files changed, 430 insertions(+), 81 deletions(-) > > create mode 100644 docs/conf.py > > create mode 100644 docs/devel/conf.py > > create mode 100644 docs/devel/index.rst > > rename docs/devel/{memory.txt => memory.rst} (85%) > > create mode 100644 docs/index.rst > > create mode 100644 docs/interop/conf.py > > create mode 100644 docs/interop/index.rst
