| Message ID | 20210223095931.16908-1-alex.bennee@linaro.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs: move CODING_STYLE into the developer documentation | expand |
On 2/23/21 10:59 AM, Alex Bennée 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> Reviewed-by: Claudio Fontana <cfontana@suse.de> Are there pointers in wiki.qemu.org that need updating? > --- > docs/devel/index.rst | 1 + > CODING_STYLE.rst => docs/devel/style.rst | 6 +++--- > README.rst | 4 +++- > scripts/fix-multiline-comments.sh | 2 +- > 4 files changed, 8 insertions(+), 5 deletions(-) > rename CODING_STYLE.rst => docs/devel/style.rst (99%) > > diff --git a/docs/devel/index.rst b/docs/devel/index.rst > index 22854e334d..ae664da00c 100644 > --- a/docs/devel/index.rst > +++ b/docs/devel/index.rst > @@ -14,6 +14,7 @@ Contents: > :maxdepth: 2 > > build-system > + style > kconfig > testing > fuzzing > diff --git a/CODING_STYLE.rst b/docs/devel/style.rst > similarity index 99% > rename from CODING_STYLE.rst > rename to docs/devel/style.rst > index 7bf4e39d48..8b0bdb3570 100644 > --- a/CODING_STYLE.rst > +++ b/docs/devel/style.rst > @@ -641,7 +641,7 @@ trace-events style > > In trace-events files, use a '0x' prefix to specify hex numbers, as in: > > -.. code-block:: > +.. code-block:: c > > some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64 > > @@ -649,14 +649,14 @@ An exception is made for groups of numbers that are hexadecimal by > convention and separated by the symbols '.', '/', ':', or ' ' (such as > PCI bus id): > > -.. code-block:: > +.. code-block:: c > > another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x" > > However, you can use '0x' for such groups if you want. Anyway, be sure that > it is obvious that numbers are in hex, ex.: > > -.. code-block:: > +.. code-block:: c > > data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x" > > 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. > > Additional information on submitting patches can be found online via > the QEMU website > diff --git a/scripts/fix-multiline-comments.sh b/scripts/fix-multiline-comments.sh > index 93f9b10669..c15a041272 100755 > --- a/scripts/fix-multiline-comments.sh > +++ b/scripts/fix-multiline-comments.sh > @@ -1,6 +1,6 @@ > #! /bin/sh > # > -# Fix multiline comments to match CODING_STYLE > +# Fix multiline comments to match docs/devel/style.rst > # > # Copyright (C) 2018 Red Hat, Inc. > # >
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 ? thanks -- PMM
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>
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> 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? Phil.
Peter Maydell <peter.maydell@linaro.org> writes: > 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 ? Well I browsed to: https://www.qemu.org/docs/master/ which re-directed me to the readthedocs URL. However it looks like: https://www.qemu.org/docs/master/devel/index.html DTRT so I can fix that. > > thanks > -- PMM
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. > 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. > > Phil.
Claudio Fontana <cfontana@suse.de> writes: > On 2/23/21 10:59 AM, Alex Bennée 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> > > Reviewed-by: Claudio Fontana <cfontana@suse.de> > > Are there pointers in wiki.qemu.org that need updating? The Contribute/StartHere wiki page redirects to Contribute but I guess it would be better to move some of that content either to the devel manual or the website. > > >> --- >> docs/devel/index.rst | 1 + >> CODING_STYLE.rst => docs/devel/style.rst | 6 +++--- >> README.rst | 4 +++- >> scripts/fix-multiline-comments.sh | 2 +- >> 4 files changed, 8 insertions(+), 5 deletions(-) >> rename CODING_STYLE.rst => docs/devel/style.rst (99%) >> >> diff --git a/docs/devel/index.rst b/docs/devel/index.rst >> index 22854e334d..ae664da00c 100644 >> --- a/docs/devel/index.rst >> +++ b/docs/devel/index.rst >> @@ -14,6 +14,7 @@ Contents: >> :maxdepth: 2 >> >> build-system >> + style >> kconfig >> testing >> fuzzing >> diff --git a/CODING_STYLE.rst b/docs/devel/style.rst >> similarity index 99% >> rename from CODING_STYLE.rst >> rename to docs/devel/style.rst >> index 7bf4e39d48..8b0bdb3570 100644 >> --- a/CODING_STYLE.rst >> +++ b/docs/devel/style.rst >> @@ -641,7 +641,7 @@ trace-events style >> >> In trace-events files, use a '0x' prefix to specify hex numbers, as in: >> >> -.. code-block:: >> +.. code-block:: c >> >> some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64 >> >> @@ -649,14 +649,14 @@ An exception is made for groups of numbers that are hexadecimal by >> convention and separated by the symbols '.', '/', ':', or ' ' (such as >> PCI bus id): >> >> -.. code-block:: >> +.. code-block:: c >> >> another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x" >> >> However, you can use '0x' for such groups if you want. Anyway, be sure that >> it is obvious that numbers are in hex, ex.: >> >> -.. code-block:: >> +.. code-block:: c >> >> data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x" >> >> 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. >> >> Additional information on submitting patches can be found online via >> the QEMU website >> diff --git a/scripts/fix-multiline-comments.sh b/scripts/fix-multiline-comments.sh >> index 93f9b10669..c15a041272 100755 >> --- a/scripts/fix-multiline-comments.sh >> +++ b/scripts/fix-multiline-comments.sh >> @@ -1,6 +1,6 @@ >> #! /bin/sh >> # >> -# Fix multiline comments to match CODING_STYLE >> +# Fix multiline comments to match docs/devel/style.rst >> # >> # Copyright (C) 2018 Red Hat, Inc. >> # >>
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.) Stefan
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
On Wed, Feb 24, 2021 at 12:19:25PM +0000, Daniel P. Berrangé wrote: > 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. Awesome! I have updated the qemu.org HTTP redirect to GitLab: https://qemu.org/docs/master/ If anyone wants to discuss RTD vs GitLab docs hosting more, please go ahead. We can change the redirect again in the future, if necessary. Stefan
On Wed, Feb 24, 2021 at 03:25:41PM +0000, Stefan Hajnoczi wrote: > On Wed, Feb 24, 2021 at 12:19:25PM +0000, Daniel P. Berrangé wrote: > > 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: > > > > > 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. > > Awesome! I have updated the qemu.org HTTP redirect to GitLab: > > https://qemu.org/docs/master/ > > If anyone wants to discuss RTD vs GitLab docs hosting more, please go > ahead. We can change the redirect again in the future, if necessary. The downside with using a HTTP redirect is that user's still see the particular hosting choice. So they are liable to bookmark these links which will break if we move again. Paolo had proposed a patch to rsync the CI content directly onto qemu.org: https://lists.gnu.org/archive/html/qemu-devel/2021-01/msg04629.html Regards, Daniel
On Wed, Feb 24, 2021 at 03:33:41PM +0000, Daniel P. Berrangé wrote: > On Wed, Feb 24, 2021 at 03:25:41PM +0000, Stefan Hajnoczi wrote: > > On Wed, Feb 24, 2021 at 12:19:25PM +0000, Daniel P. Berrangé wrote: > > > 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: > > > > > > 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. > > > > Awesome! I have updated the qemu.org HTTP redirect to GitLab: > > > > https://qemu.org/docs/master/ > > > > If anyone wants to discuss RTD vs GitLab docs hosting more, please go > > ahead. We can change the redirect again in the future, if necessary. > > The downside with using a HTTP redirect is that user's still see the > particular hosting choice. So they are liable to bookmark these > links which will break if we move again. > > Paolo had proposed a patch to rsync the CI content directly onto > qemu.org: > > https://lists.gnu.org/archive/html/qemu-devel/2021-01/msg04629.html That sounds good too. Stefan
Hi Paolo, I just noticed that scripts/fix-multiline-comments.sh has a copyright statement, but no license statement. Should that be fixed? It looks like there exist more files with the same problem (if it is a problem), for example docs/devel/loads-stores.rst (written by Peter). LICENSE says that "Source files with no licensing information are released under the GNU General Public License [...]". Does that include shell and Python scripts, documentation and other files which might not be regarded as "source files"? Or should that be updated to "Any files with no licensing information [...]" which would also include files which have neither a copyright nor a license statement? Kind regards Stefan W.
diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 22854e334d..ae664da00c 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -14,6 +14,7 @@ Contents: :maxdepth: 2 build-system + style kconfig testing fuzzing diff --git a/CODING_STYLE.rst b/docs/devel/style.rst similarity index 99% rename from CODING_STYLE.rst rename to docs/devel/style.rst index 7bf4e39d48..8b0bdb3570 100644 --- a/CODING_STYLE.rst +++ b/docs/devel/style.rst @@ -641,7 +641,7 @@ trace-events style In trace-events files, use a '0x' prefix to specify hex numbers, as in: -.. code-block:: +.. code-block:: c some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64 @@ -649,14 +649,14 @@ An exception is made for groups of numbers that are hexadecimal by convention and separated by the symbols '.', '/', ':', or ' ' (such as PCI bus id): -.. code-block:: +.. code-block:: c another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x" However, you can use '0x' for such groups if you want. Anyway, be sure that it is obvious that numbers are in hex, ex.: -.. code-block:: +.. code-block:: c data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x" 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. Additional information on submitting patches can be found online via the QEMU website diff --git a/scripts/fix-multiline-comments.sh b/scripts/fix-multiline-comments.sh index 93f9b10669..c15a041272 100755 --- a/scripts/fix-multiline-comments.sh +++ b/scripts/fix-multiline-comments.sh @@ -1,6 +1,6 @@ #! /bin/sh # -# Fix multiline comments to match CODING_STYLE +# Fix multiline comments to match docs/devel/style.rst # # Copyright (C) 2018 Red Hat, Inc. #
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> --- docs/devel/index.rst | 1 + CODING_STYLE.rst => docs/devel/style.rst | 6 +++--- README.rst | 4 +++- scripts/fix-multiline-comments.sh | 2 +- 4 files changed, 8 insertions(+), 5 deletions(-) rename CODING_STYLE.rst => docs/devel/style.rst (99%)