Documents not in sphinx toctree

Documents not in sphinx toctree

[Marc-André Lureau]

[-- Attachment #1: Type: text/plain, Size: 413 bytes --]

Hi,

By running sphinx over the docs/ directory (like readthedocs.org presumably
does), it finds a couple of rst documents that are not referenced:
- cpu-hotplug.rst
- microvm.rst
- pr-manager.rst
- virtio-net-failover.rst
- virtio-pmem.rst

Shouldn't they be?

If not (I wonder why), there should be a way to explicitly exclude those,
and avoid extra warnings.

thanks

-- 
Marc-André Lureau

[-- Attachment #2: Type: text/html, Size: 699 bytes --]

Re: Documents not in sphinx toctree

[Peter Maydell]

On Thu, 5 Nov 2020 at 16:14, Marc-André Lureau
<marcandre.lureau@gmail.com> wrote:
> By running sphinx over the docs/ directory (like readthedocs.org presumably does), it finds a couple of rst documents that are not referenced:
> - cpu-hotplug.rst
> - microvm.rst
> - pr-manager.rst
> - virtio-net-failover.rst
> - virtio-pmem.rst
>
> Shouldn't they be?

These all need to be moved into the correct manual. That
might involve splitting them into several pieces so that
the different pieces can go into different manuals.

The difficulty is that this requires attention from somebody
who has at least some vague idea of the contents and who
can move them around appropriately.

In the meantime, they're in exactly the same boat as
the various *.txt documents in docs/ -- old stuff
that doesn't end up in the user-facing manuals and which
nobody's got round to properly integrating into the docs yet.

> If not (I wonder why), there should be a way to explicitly
> exclude those, and avoid extra warnings.

The only thing that runs sphinx directly on the docs
is readthedocs, and it doesn't care about warnings :-)

thanks
-- PMM

Re: Documents not in sphinx toctree

[Jens Freimann]

On Thu, Nov 05, 2020 at 04:19:00PM +0000, Peter Maydell wrote:
>On Thu, 5 Nov 2020 at 16:14, Marc-André Lureau
><marcandre.lureau@gmail.com> wrote:
>> By running sphinx over the docs/ directory (like readthedocs.org presumably does), it finds a couple of rst documents that are not referenced:
>> - cpu-hotplug.rst
>> - microvm.rst
>> - pr-manager.rst
>> - virtio-net-failover.rst

Given the current structure of the content in
https://qemu.readthedocs.io/en/latest/,
would adding this as a new bullet in "QEMU System Emulation User’s
Guide" be the right thing to do?  

regards,
Jens 

Re: Documents not in sphinx toctree

[Peter Maydell]

On Thu, 5 Nov 2020 at 16:36, Jens Freimann <jfreimann@redhat.com> wrote:
>
> On Thu, Nov 05, 2020 at 04:19:00PM +0000, Peter Maydell wrote:
> >On Thu, 5 Nov 2020 at 16:14, Marc-André Lureau
> ><marcandre.lureau@gmail.com> wrote:
> >> By running sphinx over the docs/ directory (like readthedocs.org presumably does), it finds a couple of rst documents that are not referenced:
> >> - cpu-hotplug.rst
> >> - microvm.rst
> >> - pr-manager.rst
> >> - virtio-net-failover.rst
>
> Given the current structure of the content in
> https://qemu.readthedocs.io/en/latest/,
> would adding this as a new bullet in "QEMU System Emulation User’s
> Guide" be the right thing to do?

Adding which?

For cpu-hotplug.rst:
 I guess the system manual. The document has a bit of a
 "tutorial" feel which doesn't entirely fit the rest of the
 manuals.

For microvm.rst:
 docs/system/target-i386.rst should be split into
 documentation for each of the machine models separately
 (as a list of links to docs in docs/system/i386/, similar
 to the structure of target-arm.rst and docs/system/arm/).
 Then microvm.rst can go into docs/system/i386.

For pr-manager.rst:
 The parts that are documenting the qemu-pr-helper invocation
 should turn into a docs/tools/ manpage for it.
 The other parts should go in the system manual I guess.

For virtio-net-failover.rst:
 Should go under the "Network emulation" part of the system
 manual, I think.

thanks
-- PMM

Re: Documents not in sphinx toctree

[Pankaj Gupta]

> > >> By running sphinx over the docs/ directory (like readthedocs.org presumably does), it finds a couple of rst documents that are not referenced:
> > >> - cpu-hotplug.rst
> > >> - microvm.rst
> > >> - pr-manager.rst
> > >> - virtio-net-failover.rst
> >
> > Given the current structure of the content in
> > https://qemu.readthedocs.io/en/latest/,
> > would adding this as a new bullet in "QEMU System Emulation User’s
> > Guide" be the right thing to do?
>
> Adding which?
>
> For cpu-hotplug.rst:
>  I guess the system manual. The document has a bit of a
>  "tutorial" feel which doesn't entirely fit the rest of the
>  manuals.
>
> For microvm.rst:
>  docs/system/target-i386.rst should be split into
>  documentation for each of the machine models separately
>  (as a list of links to docs in docs/system/i386/, similar
>  to the structure of target-arm.rst and docs/system/arm/).
>  Then microvm.rst can go into docs/system/i386.
>
> For pr-manager.rst:
>  The parts that are documenting the qemu-pr-helper invocation
>  should turn into a docs/tools/ manpage for it.
>  The other parts should go in the system manual I guess.
>
> For virtio-net-failover.rst:
>  Should go under the "Network emulation" part of the system
>  manual, I think.

Maybe existing memory emulation 'txt' files need to be converted into '.rst',
and along with virtio-pmem.rst could be moved to a new section?

Thanks,
Pankaj

Re: Documents not in sphinx toctree

[Paolo Bonzini]

On 05/11/20 17:12, Marc-André Lureau wrote:
> Hi,
> 
> By running sphinx over the docs/ directory (like readthedocs.org 
> <http://readthedocs.org> presumably does), it finds a couple of rst 
> documents that are not referenced:
> - cpu-hotplug.rst
> - microvm.rst
> - pr-manager.rst
> - virtio-net-failover.rst
> - virtio-pmem.rst
> 
> Shouldn't they be?
> 
> If not (I wonder why), there should be a way to explicitly exclude 
> those, and avoid extra warnings.

They were written or converted after we had decided to switch to Sphinx, 
but before we had a proper manual structure.

The problem is finding them a place...

Paolo