Re: [PATCH v3 00/33] Convert qemu-doc to rST
On Tue, Mar 03, 2020 at 05:35:01PM +, Peter Maydell wrote: > On Fri, 28 Feb 2020 at 15:36, Peter Maydell wrote: > > > > Hi; this series does a complete conversion of qemu-doc from > > Texinfo to rST, including the hxtool-generated parts and > > creation of the qemu.1 manpage from rST. > > > > Advance notice: I would like to put these into a pull > request at the end of this week. This is your opportunity > to say "that would be a bad idea", "I need X more time > to review it", etc :-) I tried to probe some of the generated docs; I couldn't spot something that is glaring. (Granted, I didn't spend a _whole_ lot of time.) And I'm with Paolo — yes, let's get this merged, and address other issues as follow-ups :-) -- /kashyap
Re: [PATCH v3 00/33] Convert qemu-doc to rST
Peter Maydell writes: > On Fri, 28 Feb 2020 at 15:36, Peter Maydell wrote: >> >> Hi; this series does a complete conversion of qemu-doc from >> Texinfo to rST, including the hxtool-generated parts and >> creation of the qemu.1 manpage from rST. >> > > Advance notice: I would like to put these into a pull > request at the end of this week. This is your opportunity > to say "that would be a bad idea", "I need X more time > to review it", etc :-) Just merge it, we can fix things up afterwards if we need to but it's a big step in the right direction. > > thanks > -- PMM -- Alex Bennée
Re: [PATCH v3 00/33] Convert qemu-doc to rST
On 03/03/20 18:35, Peter Maydell wrote: > Advance notice: I would like to put these into a pull > request at the end of this week. This is your opportunity > to say "that would be a bad idea", "I need X more time > to review it", etc :-) > On the contrary, it's a great idea. :) Paolo
Re: [PATCH v3 00/33] Convert qemu-doc to rST
On Fri, 28 Feb 2020 at 15:36, Peter Maydell wrote: > > Hi; this series does a complete conversion of qemu-doc from > Texinfo to rST, including the hxtool-generated parts and > creation of the qemu.1 manpage from rST. > Advance notice: I would like to put these into a pull request at the end of this week. This is your opportunity to say "that would be a bad idea", "I need X more time to review it", etc :-) thanks -- PMM
Re: [PATCH v3 00/33] Convert qemu-doc to rST
Peter Maydell writes: > Hi; this series does a complete conversion of qemu-doc from > Texinfo to rST, including the hxtool-generated parts and > creation of the qemu.1 manpage from rST. > > It's marked v3 because it's a development of the v2 that > Paolo sent out earlier this week. I should mention the whole thing is: Tested-by: Alex Bennée by virtue of my custom rtd branch: https://qemu-stsquad.readthedocs.io/en/doc-updates/index.html -- Alex Bennée
Re: [PATCH v3 00/33] Convert qemu-doc to rST
On Fri, 28 Feb 2020 at 21:20, Stefan Weil wrote: > Maybe it is sufficient to update qemu.nsi after that series was merged. If you're happy to do it that way round I think that would certainly make life easier in trying to get this series merged without too much delay. > Do you think that all documentation should be part of the Windows > installer, although it is also available online? Too much documentation > can be confusing, because it makes it more difficult to find the right > entry. I don't have a strong opinion here, but: * the contents that were in qemu-doc.html will now be in the various Sphinx manuals, so if we want to install any docs locally at all then installing at least the system/ manual would be the equivalent of the old qemu-doc * is there a strong reason for the Windows installer not to just install the same set of HTML docs that the Linux 'make install' does? Three possible choices: (1) don't install any docs locally at all (rely on the online docs) (2) install just the 'system' manual (this will catch most of the documentation relevant for Windows, but misses a few bits like the guest-agent docs which might still matter for Windows users) (3) install all the manuals (this will include some manuals or sections definitely not of interest for Windows, like the linux-user manual) thanks -- PMM
Re: [PATCH v3 00/33] Convert qemu-doc to rST
Am 28.02.20 um 19:36 schrieb Peter Maydell: > Hi Stefan -- I meant to cc you on these but forgot, relating to the > "qemu.nsi needs updating to know that it should install > Sphinx documentation these days" part... > > On Fri, 28 Feb 2020 at 15:36, Peter Maydell wrote: [...] >> A couple of notes: >> * I haven't actually been in a position to test the cocoa.m >>update of the HTML filename >> * qemu.nsi (the Windows installer config file) thinks that >>qemu-doc.html is the only doc file it needs to know about, >>which is clearly wrong. However I don't have any idea about >>the Windows installer to be able to update or test it... Maybe it is sufficient to update qemu.nsi after that series was merged. Do you think that all documentation should be part of the Windows installer, although it is also available online? Too much documentation can be confusing, because it makes it more difficult to find the right entry. Kind regards Stefan
Re: [PATCH v3 00/33] Convert qemu-doc to rST
Hi Stefan -- I meant to cc you on these but forgot, relating to the "qemu.nsi needs updating to know that it should install Sphinx documentation these days" part... On Fri, 28 Feb 2020 at 15:36, Peter Maydell wrote: > > Hi; this series does a complete conversion of qemu-doc from > Texinfo to rST, including the hxtool-generated parts and > creation of the qemu.1 manpage from rST. > > It's marked v3 because it's a development of the v2 that > Paolo sent out earlier this week. > > Changes from v2: > * I made the various review-comment fixes I suggested in >replies to Paolo's series > * rebased on current master > * new patches at the end of the series which do the conversion >of the .hx file doc fragments to rST >(I did part of this semi-by-hand and then qemu-options.hx >entirely automatically) > * new patches which generate the qemu.1 manpage with Sphinx > * new patches which remove the old qemu-doc makefile runes >and other references to it > * new patches which delete the old texinfo sources, etc > > The only thing left still using Texinfo after this is the > docs autogenerated from the QAPI doc-comments, which are > their own standalone html and manpages so not affected by this. > > A couple of notes: > * I haven't actually been in a position to test the cocoa.m >update of the HTML filename > * qemu.nsi (the Windows installer config file) thinks that >qemu-doc.html is the only doc file it needs to know about, >which is clearly wrong. However I don't have any idea about >the Windows installer to be able to update or test it... > > The conversion is a little rough around the edges in a few > place (mostly I have noted in commit messages when this is > the case) but I would like to argue for (assuming we're happy > with the series broadly) taking it into master and then refining > it in-place. Having it out-of-tree for long is an invitation > to conflicts and to accidentally losing docs updates if they > hit master as changes to the texi or hx files before this > series goes in. > > You can find a prerendered set of docs at > https://people.linaro.org/~peter.maydell/qdoc-no-texi/ > (the interesting part is the system emulation user's guide, > mostly), and a copy of the new manpage at > https://people.linaro.org/~peter.maydell/qemu.1 > (download and examine with 'man -l path/to/qemu.1'). > > thanks > -- PMM
[PATCH v3 00/33] Convert qemu-doc to rST
Hi; this series does a complete conversion of qemu-doc from Texinfo to rST, including the hxtool-generated parts and creation of the qemu.1 manpage from rST. It's marked v3 because it's a development of the v2 that Paolo sent out earlier this week. Changes from v2: * I made the various review-comment fixes I suggested in replies to Paolo's series * rebased on current master * new patches at the end of the series which do the conversion of the .hx file doc fragments to rST (I did part of this semi-by-hand and then qemu-options.hx entirely automatically) * new patches which generate the qemu.1 manpage with Sphinx * new patches which remove the old qemu-doc makefile runes and other references to it * new patches which delete the old texinfo sources, etc The only thing left still using Texinfo after this is the docs autogenerated from the QAPI doc-comments, which are their own standalone html and manpages so not affected by this. A couple of notes: * I haven't actually been in a position to test the cocoa.m update of the HTML filename * qemu.nsi (the Windows installer config file) thinks that qemu-doc.html is the only doc file it needs to know about, which is clearly wrong. However I don't have any idea about the Windows installer to be able to update or test it... The conversion is a little rough around the edges in a few place (mostly I have noted in commit messages when this is the case) but I would like to argue for (assuming we're happy with the series broadly) taking it into master and then refining it in-place. Having it out-of-tree for long is an invitation to conflicts and to accidentally losing docs updates if they hit master as changes to the texi or hx files before this series goes in. You can find a prerendered set of docs at https://people.linaro.org/~peter.maydell/qdoc-no-texi/ (the interesting part is the system emulation user's guide, mostly), and a copy of the new manpage at https://people.linaro.org/~peter.maydell/qemu.1 (download and examine with 'man -l path/to/qemu.1'). thanks -- PMM Kashyap Chamarthy (1): docs/system: Convert qemu-cpu-models.texi to rST Paolo Bonzini (13): qemu-doc: convert user-mode emulation to a separate Sphinx manual qemu-doc: remove target OS documentation texi2pod: parse @include directives outside "@c man" blocks qemu-doc: split CPU models doc between MIPS and x86 parts qemu-doc: split qemu-doc.texi in multiple files qemu-doc: extract common system emulator documentation from the PC section qemu-doc: move system requirements chapter inside PC section qemu-doc: split target sections to separate files qemu-doc: move qemu-tech.texi into main section qemu-doc: move included files to docs/system qemu-doc: remove indices other than findex docs/system: put qemu-block-drivers body in an included file docs/system: convert Texinfo documentation to rST Peter Maydell (19): qemu-doc: Remove the "CPU emulation" part of the "Implementation notes" docs: Create defs.rst.inc as a place to define substitutions docs/system: Convert security.texi to rST format docs/system: convert managed startup to rST. docs/system: convert the documentation of deprecated features to rST. hmp-commands.hx: Add rST documentation fragments hmp-commands-info.hx: Add rST documentation fragments doc/scripts/hxtool.py: Strip trailing ':' from DEFHEADING/ARCHHEADING docs: Roll semihosting option information into qemu-options.hx docs: Roll -prom-env and -g target-specific info into qemu-options.hx scripts/hxtool-conv: Archive script used in qemu-options.hx conversion qemu-options.hx: Add rST documentation fragments qemu-options.hx: Fix up the autogenerated rST docs: Split out sections for the manpage into .rst.inc files docs: Generate qemu.1 manpage with Sphinx ui/cocoa.m: Update documentation file and pathname docs: Stop building qemu-doc docs: Remove old texinfo sources *.hx: Remove all the STEXI/ETEXI blocks docs/specs/ivshmem-spec.txt |4 +- Makefile | 47 +- .gitignore|3 - MAINTAINERS |7 +- docs/conf.py |6 + docs/defs.rst.inc | 15 + docs/index.html.in|2 +- docs/index.rst|1 + docs/qemu-cpu-models.texi | 677 -- docs/sphinx/hxtool.py | 10 +- docs/system/build-platforms.rst | 79 + docs/system/conf.py |8 +- docs/system/cpu-models-mips.rst.inc | 105 + docs/system/cpu-models-x86.rst.inc| 365 + docs/system/deprecated.rst| 446 + docs/system/device-url-syntax.rst.inc | 228 + docs/system/gdb.rst | 81 + docs/system/images.rst
