| Message ID | 20200217155415.30949-1-peter.maydell@linaro.org (mailing list archive) |
|---|---|
| Headers | show |
| Series | docs: Create a 'tools' manual | expand |
On 2/17/20 7:54 AM, Peter Maydell wrote: > Peter Maydell (3): > docs: Create new 'tools' manual > docs: Move qemu-option-trace.rst.inc to docs/ > docs: Move tools documentation to tools manual Reviewed-by: Richard Henderson <richard.henderson@linaro.org> r~
On 17/02/20 16:54, Peter Maydell wrote: > This patchset creates the new 'tools' manual that we've > decided we should have, and moves 5 existing documents to it: > > docs/interop/qemu-img.rst > docs/interop/qemu-nbd.rst > docs/interop/virtfs-proxy-helper.rst > docs/interop/qemu-trace-stap.rst > docs/interop/virtiofsd.rst > > This change will conflict with the QAPI-doc-comment-to-rST > patchset because they both change the docs/interop makefile > rules, but I expect this one to get in to master first; > the other needs a respin at some point anyhow. Acked-by: Paolo Bonzini <pbonzini@redhat.com> We can move them back to the system manual once it's converted to rST, but for now it's the best solution. (In fact, I am willing to do the conversion from texi to rST if: 1) someone else helps with the .hx parts; 2) we accept that the current structure of the manual isn't great but we agree to reorganize everything after the conversion). Paolo
On Mon, 17 Feb 2020 at 16:04, Paolo Bonzini <pbonzini@redhat.com> wrote: > > On 17/02/20 16:54, Peter Maydell wrote: > > This patchset creates the new 'tools' manual that we've > > decided we should have, and moves 5 existing documents to it: > > > > docs/interop/qemu-img.rst > > docs/interop/qemu-nbd.rst > > docs/interop/virtfs-proxy-helper.rst > > docs/interop/qemu-trace-stap.rst > > docs/interop/virtiofsd.rst > > > > This change will conflict with the QAPI-doc-comment-to-rST > > patchset because they both change the docs/interop makefile > > rules, but I expect this one to get in to master first; > > the other needs a respin at some point anyhow. > > Acked-by: Paolo Bonzini <pbonzini@redhat.com> > > We can move them back to the system manual once it's converted to rST, > but for now it's the best solution. I think they can reasonably continue to live in tools/ even once we've got more stuff in system/. > (In fact, I am willing to do the conversion from texi to rST if: 1) > someone else helps with the .hx parts; 2) we accept that the current > structure of the manual isn't great but we agree to reorganize > everything after the conversion). Yes, I'm definitely working on a "we can reshuffle stuff later, but let's get the basic conversion done first" basis. The mechanics for handling .hx files are already in the tree; I can either help or work on the bit of qemu.1 that uses those. Kashyap has volunteered to do qemu-cpu-models.texi. I have patches on-list that try to do the QAPI doc-comments. I think the next thing after this is to take chunks of documentation that are currently used in qemu-doc.html but not put into the qemu.1 manpage (ie which aren't in the 'man begin'/'man end' sections), and convert those into individual .rst files to go into docs/system: * docs/security.texi * qemu-tech.texi * qemu-deprecated.texi * various bits of qemu-doc.texi that don't go in the manpage and that are coherent chunks of documentation, eg "Supported build platforms", the various "$ARCH System emulator" sections That will whittle qemu-doc.texi down to more or less just the contents of the manpage. Then we can convert that part to rST. I note that softfreeze is now 1 month away -- we should decide whether we think we can get this basically all done by then, or whether there's a good "pause point" we'd like to use where, say, most of qemu-doc.texi remains as it is, or where it retains just the content that goes into the qemu.1 manpage. thanks -- PMM
On 17/02/20 17:18, Peter Maydell wrote: > The mechanics for handling .hx files are already in the tree; > I can either help or work on the bit of qemu.1 that uses those. Right, basically if somebody else does qemu.1 I won't complain. :) But recently I retested the makeinfo+pandoc magic formulae that convert the rest into rST and they work so I can take care of that part. > Kashyap has volunteered to do qemu-cpu-models.texi. > I have patches on-list that try to do the QAPI doc-comments. > > I think the next thing after this is to take chunks of documentation > that are currently used in qemu-doc.html but not put into the > qemu.1 manpage (ie which aren't in the 'man begin'/'man end' > sections), and convert those into individual .rst files > to go into docs/system: > > * docs/security.texi > * qemu-tech.texi > * qemu-deprecated.texi > * various bits of qemu-doc.texi that don't go in the > manpage and that are coherent chunks of documentation, > eg "Supported build platforms", the various "$ARCH System emulator" > sections One initial step here is to split qemu-doc.texi into separate Texinfo files. I can take a look at that as well. Paolo > That will whittle qemu-doc.texi down to more or less just > the contents of the manpage. Then we can convert that > part to rST. > > I note that softfreeze is now 1 month away -- we should > decide whether we think we can get this basically all > done by then, or whether there's a good "pause point" > we'd like to use where, say, most of qemu-doc.texi > remains as it is, or where it retains just the > content that goes into the qemu.1 manpage.
This patchset creates the new 'tools' manual that we've decided we should have, and moves 5 existing documents to it: docs/interop/qemu-img.rst docs/interop/qemu-nbd.rst docs/interop/virtfs-proxy-helper.rst docs/interop/qemu-trace-stap.rst docs/interop/virtiofsd.rst This change will conflict with the QAPI-doc-comment-to-rST patchset because they both change the docs/interop makefile rules, but I expect this one to get in to master first; the other needs a respin at some point anyhow. thanks -- PMM Peter Maydell (3): docs: Create new 'tools' manual docs: Move qemu-option-trace.rst.inc to docs/ docs: Move tools documentation to tools manual Makefile | 41 +++++++++++-------- docs/index.html.in | 1 + docs/index.rst | 1 + docs/interop/conf.py | 12 ------ docs/interop/index.rst | 5 --- docs/{interop => }/qemu-option-trace.rst.inc | 0 docs/{interop => tools}/conf.py | 7 ++-- docs/tools/index.rst | 17 ++++++++ docs/{interop => tools}/qemu-img.rst | 2 +- docs/{interop => tools}/qemu-nbd.rst | 2 +- docs/{interop => tools}/qemu-trace-stap.rst | 0 .../virtfs-proxy-helper.rst | 0 docs/{interop => tools}/virtiofsd.rst | 0 13 files changed, 48 insertions(+), 40 deletions(-) rename docs/{interop => }/qemu-option-trace.rst.inc (100%) copy docs/{interop => tools}/conf.py (80%) create mode 100644 docs/tools/index.rst rename docs/{interop => tools}/qemu-img.rst (99%) rename docs/{interop => tools}/qemu-nbd.rst (99%) rename docs/{interop => tools}/qemu-trace-stap.rst (100%) rename docs/{interop => tools}/virtfs-proxy-helper.rst (100%) rename docs/{interop => tools}/virtiofsd.rst (100%)