Re: [PATCH] docs: move CODING_STYLE into the developer documentation

From: "Daniel P. Berrangé" <berrange@redhat.com>
To: Stefan Hajnoczi <stefanha@redhat.com>
Cc: "Philippe Mathieu-Daudé" <philmd@redhat.com>,
	"Thomas Huth" <thuth@redhat.com>,
	"Alex Bennée" <alex.bennee@linaro.org>,
	"QEMU Developers" <qemu-devel@nongnu.org>,
	"Peter Maydell" <peter.maydell@linaro.org>
Subject: Re: [PATCH] docs: move CODING_STYLE into the developer documentation
Date: Wed, 24 Feb 2021 12:19:25 +0000	[thread overview]
Message-ID: <YDZETVhPKm7H2My2@redhat.com> (raw)
In-Reply-To: <YDZDSY3G9+KpgJsE@stefanha-x1.localdomain>

On Wed, Feb 24, 2021 at 12:15:05PM +0000, Stefan Hajnoczi wrote:
> On Tue, Feb 23, 2021 at 01:37:45PM +0000, Alex Bennée wrote:
> > 
> > Philippe Mathieu-Daudé <philmd@redhat.com> writes:
> > 
> > > On 2/23/21 12:29 PM, Philippe Mathieu-Daudé wrote:
> > >> On 2/23/21 12:07 PM, Peter Maydell wrote:
> > >>> On Tue, 23 Feb 2021 at 10:02, Alex Bennée <alex.bennee@linaro.org> wrote:
> > >>>>
> > >>>> There is no particular reason to keep this on it's own in the root of
> > >>>> the tree. Move it into the rest of the fine developer manual and fixup
> > >>>> any links to it. The only tweak I've made is to fix the code-block
> > >>>> annotations to mention the language C.
> > >>>>
> > >>>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> > >>>> ---
> > >>>> diff --git a/README.rst b/README.rst
> > >>>> index ce39d89077..f5d41e59b1 100644
> > >>>> --- a/README.rst
> > >>>> +++ b/README.rst
> > >>>> @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git
> > >>>>  format-patch' and/or 'git send-email' to format & send the mail to the
> > >>>>  qemu-devel@nongnu.org mailing list. All patches submitted must contain
> > >>>>  a 'Signed-off-by' line from the author. Patches should follow the
> > >>>> -guidelines set out in the CODING_STYLE.rst file.
> > >>>> +guidelines set out in the `style section
> > >>>> +<https://qemu.readthedocs.io/en/latest/devel/style.html>` of
> > >>>> +the Developers Guide.
> > >>>
> > >>> This is the first instance of a qemu.readthedocs.io URL in the
> > >>> tree. Do we really want to have our references to our documentation
> > >>> be to a third party website ?
> > >> 
> > >> We can use https://www.qemu.org/docs/master/devel/style.html:
> > >> 
> > >> $ curl https://www.qemu.org/docs/master/devel/style.html
> > >> <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
> > >> <html><head>
> > >> <title>302 Found</title>
> > >> </head><body>
> > >> <h1>Found</h1>
> > >> <p>The document has moved <a
> > >> href="https://qemu.readthedocs.io/en/latest/devel/style.html">here</a>.</p>
> > >> </body></html>
> > 
> > I think if we treat the qemu.org domain as being the canonical URL and
> > then let it redirect where it wants. 
> 
> Yes, let's treat qemu.org as the canonical domain so we have the ability
> to change locations easily later.
> 
> > > Or even better since we have a job pushing to Gitlab pages
> > > accessible on https://qemu-project.gitlab.io/qemu/:
> > >
> > > https://qemu-project.gitlab.io/qemu/devel/style.html
> > >
> > > Maybe the https://www.qemu.org/docs/ redirect should
> > > go to gitlab page now?
> > 
> > It could do either, I think the result is exactly the same.
> 
> Standarizing project infrastructure on GitLab CI seems good to me. That
> way developers will be able to reuse their CI knowledge and won't have
> to learn other systems (like readthedocs).
> 
> However, I don't see .gitlab-ci.yml directives that build the docs and
> publish a static page yet. Is anyone volunteering to do this? (It can be
> done as a separate step from this patch.)

The very last job (called 'pages') in .gitlab-ci.yml does this.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|