Re: [Qemu-devel] Sphinx and docs/index.rst: dead code?

[John Snow <jsnow@redhat.com>]

On 7/25/19 12:42 PM, Peter Maydell wrote:
> On Thu, 25 Jul 2019 at 17:34, John Snow <jsnow@redhat.com> wrote:
>> Yup; I think a single point of entry would be nice -- I think we need to
>> start hosting our sphinx documentation because it's confusing that we
>> have both the traditional manual (hosted by Stefan Weil) and this newer
>> one that isn't available anywhere.
>>
>> The interop manual in particular is crucial to get hosted.
> 
> Yes, this would be a good thing.
> 
>> We could perhaps formalize this as follows:
>>
>> - index.rst, which is an "absolutely everything included" single point
>> of entry manual for developers and contributors,
>>
>> - user.rst, which could be a single point of entry for end users, to be
>> bundled in distro packaging.
> 
> This means you'll end up building 90% of our documentation twice,
> which is something I was trying to avoid with the current setup.
> 

Why? Wouldn't it suffice to build just one of the top-level docs just once?

(I guess if you later decided to build the other top-level doc later it
would duplicate the work, but is that the usual case?)

> It occurs to me that we don't necessarily need the 'top level'
> page to be generated by Sphinx -- we could just ship an index.html
> which has helpful links to the individual manuals.
> 

True; we can leave it as a manual process and check the build artifact
into the repo if we want. [We likely ought to leave the source in the
tree in that case though, if we want to update the theming and other stuff.]

> (https://wiki.qemu.org/Features/Documentation is the current
> plan and lists the various manuals we'll end up with. 'user'
> in that plan means the documentation for the user-mode emulation.)
> 

Ah, whoops -- sorry for the namespace collision. I'll call it
'user-manual' or something instead if I talk about this in the future.

Thanks for the wiki page.

> thanks
> -- PMM
>