[0/4] docs: add docs about use of automatic cleanup functions
mbox series

Message ID 20190823163931.7442-1-berrange@redhat.com
Headers show
Series
  • docs: add docs about use of automatic cleanup functions
Related show

Message

Daniel P. Berrangé Aug. 23, 2019, 4:39 p.m. UTC
This is ostensibly about adding docs for the g_autofree/g_autoptr
macros. As part of doing that, however, the existing HACKING doc
is merged into the CODING_STYLE doc and the text is converted to
markdown with a table of contents.

Daniel P. Berrangé (4):
  docs: convert CODING_STYLE and HACKING to markdown syntax
  docs: merge HACKING.md contents into CODING_STYLE.md
  docs: document use of automatic cleanup functions in glib
  docs: add table of contents to CODING_STYLE.md

 CODING_STYLE    | 216 -----------------
 CODING_STYLE.md | 613 ++++++++++++++++++++++++++++++++++++++++++++++++
 HACKING         | 257 --------------------
 README          |   2 +-
 4 files changed, 614 insertions(+), 474 deletions(-)
 delete mode 100644 CODING_STYLE
 create mode 100644 CODING_STYLE.md
 delete mode 100644 HACKING

Comments

Marc-André Lureau Aug. 23, 2019, 9:48 p.m. UTC | #1
Hi

On Fri, Aug 23, 2019 at 8:41 PM Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> This is ostensibly about adding docs for the g_autofree/g_autoptr
> macros. As part of doing that, however, the existing HACKING doc
> is merged into the CODING_STYLE doc and the text is converted to
> markdown with a table of contents.

Why not rst, so it can integrate with the rest of qemu sphinx doc?

(markdown is quite poor when it comes to documenting code or
cross-referencing etc)



>
> Daniel P. Berrangé (4):
>   docs: convert CODING_STYLE and HACKING to markdown syntax
>   docs: merge HACKING.md contents into CODING_STYLE.md
>   docs: document use of automatic cleanup functions in glib
>   docs: add table of contents to CODING_STYLE.md
>
>  CODING_STYLE    | 216 -----------------
>  CODING_STYLE.md | 613 ++++++++++++++++++++++++++++++++++++++++++++++++
>  HACKING         | 257 --------------------
>  README          |   2 +-
>  4 files changed, 614 insertions(+), 474 deletions(-)
>  delete mode 100644 CODING_STYLE
>  create mode 100644 CODING_STYLE.md
>  delete mode 100644 HACKING
>
> --
> 2.21.0
>
>
Alex Bennée Aug. 28, 2019, 12:30 p.m. UTC | #2
Marc-André Lureau <marcandre.lureau@gmail.com> writes:

> Hi
>
> On Fri, Aug 23, 2019 at 8:41 PM Daniel P. Berrangé <berrange@redhat.com> wrote:
>>
>> This is ostensibly about adding docs for the g_autofree/g_autoptr
>> macros. As part of doing that, however, the existing HACKING doc
>> is merged into the CODING_STYLE doc and the text is converted to
>> markdown with a table of contents.
>
> Why not rst, so it can integrate with the rest of qemu sphinx doc?
>
> (markdown is quite poor when it comes to documenting code or
> cross-referencing etc)

I was going to say markdown does have the advantage of being renderable
on the fly on code hosting sites but it appears it works on
gitlab/github so that is an argument for being consistent with the rest
of the docs.

Does anyone know what is left to get the publishing pipeline up and
running and the results linked to from www.qemu.org?

>
>
>
>>
>> Daniel P. Berrangé (4):
>>   docs: convert CODING_STYLE and HACKING to markdown syntax
>>   docs: merge HACKING.md contents into CODING_STYLE.md
>>   docs: document use of automatic cleanup functions in glib
>>   docs: add table of contents to CODING_STYLE.md
>>
>>  CODING_STYLE    | 216 -----------------
>>  CODING_STYLE.md | 613 ++++++++++++++++++++++++++++++++++++++++++++++++
>>  HACKING         | 257 --------------------
>>  README          |   2 +-
>>  4 files changed, 614 insertions(+), 474 deletions(-)
>>  delete mode 100644 CODING_STYLE
>>  create mode 100644 CODING_STYLE.md
>>  delete mode 100644 HACKING
>>
>> --
>> 2.21.0
>>
>>


--
Alex Bennée
Daniel P. Berrangé Aug. 28, 2019, 1:07 p.m. UTC | #3
On Wed, Aug 28, 2019 at 01:30:15PM +0100, Alex Bennée wrote:
> 
> Marc-André Lureau <marcandre.lureau@gmail.com> writes:
> 
> > Hi
> >
> > On Fri, Aug 23, 2019 at 8:41 PM Daniel P. Berrangé <berrange@redhat.com> wrote:
> >>
> >> This is ostensibly about adding docs for the g_autofree/g_autoptr
> >> macros. As part of doing that, however, the existing HACKING doc
> >> is merged into the CODING_STYLE doc and the text is converted to
> >> markdown with a table of contents.
> >
> > Why not rst, so it can integrate with the rest of qemu sphinx doc?
> >
> > (markdown is quite poor when it comes to documenting code or
> > cross-referencing etc)
> 
> I was going to say markdown does have the advantage of being renderable
> on the fly on code hosting sites but it appears it works on
> gitlab/github so that is an argument for being consistent with the rest
> of the docs.

I picked markdown because most projects seem to use a README.md
and CONTRIBUTING.md file with github/gitlab, but if those sites
cope with .rst for those files too, there's no reason not to use
.rst.

> Does anyone know what is left to get the publishing pipeline up and
> running and the results linked to from www.qemu.org?


Regards,
Daniel