Google Season of Docs

classic Classic list List threaded Threaded
47 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Google Season of Docs

Boost - Dev mailing list
Hi,

The registration for organization is now open.
If anyone is interested in managing this project and wish to talk about
now, please let me know. I've got some experience now managing the Google
Summer of Code and can help with GSoD too.

Cheers,
David

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
I can do the management. I posted to the list a few days ago looking for
interested mentors, but got no volunteers.


El mar., 14 abr. 2020 a las 8:53, David Bellot via Boost (<
[hidden email]>) escribió:

> Hi,
>
> The registration for organization is now open.
> If anyone is interested in managing this project and wish to talk about
> now, please let me know. I've got some experience now managing the Google
> Summer of Code and can help with GSoD too.
>
> Cheers,
> David
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
Hi,

I would like to help with the organization as well if multiple organizers
are allowed.

Best,
Cem



Am Di., 14. Apr. 2020 um 23:37 Uhr schrieb Damian Vicino via Boost <
[hidden email]>:

> I can do the management. I posted to the list a few days ago looking for
> interested mentors, but got no volunteers.
>
>
> El mar., 14 abr. 2020 a las 8:53, David Bellot via Boost (<
> [hidden email]>) escribió:
>
> > Hi,
> >
> > The registration for organization is now open.
> > If anyone is interested in managing this project and wish to talk about
> > now, please let me know. I've got some experience now managing the Google
> > Summer of Code and can help with GSoD too.
> >
> > Cheers,
> > David
> >
> > _______________________________________________
> > Unsubscribe & other changes:
> > http://lists.boost.org/mailman/listinfo.cgi/boost
> >
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 4/14/20 5:52 AM, David Bellot via Boost wrote:

> Hi,
>
> The registration for organization is now open.
> If anyone is interested in managing this project and wish to talk about
> now, please let me know. I've got some experience now managing the Google
> Summer of Code and can help with GSoD too.
>
> Cheers,
> David
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
>

Has anyone manifested interest in actually writing documentation?  If
so, for what software?

Robert Ramey

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
so far, Damian and Cem are interested to help on this project.

On Sun, Apr 19, 2020 at 1:14 AM Robert Ramey via Boost <
[hidden email]> wrote:

> On 4/14/20 5:52 AM, David Bellot via Boost wrote:
> > Hi,
> >
> > The registration for organization is now open.
> > If anyone is interested in managing this project and wish to talk about
> > now, please let me know. I've got some experience now managing the Google
> > Summer of Code and can help with GSoD too.
> >
> > Cheers,
> > David
> >
> > _______________________________________________
> > Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
> >
>
> Has anyone manifested interest in actually writing documentation?  If
> so, for what software?
>
> Robert Ramey
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
Hi Robert,

good question. I can only speak for Boost/numeric/ublas.
Our documentation needs to be ported from pure html to rst code with sphinx.
I would like to add examples and doxygen gegenerated reference section.

Best,
Cem

Am Sa., 18. Apr. 2020 um 23:41 Uhr schrieb David Bellot via Boost <
[hidden email]>:

> so far, Damian and Cem are interested to help on this project.
>
> On Sun, Apr 19, 2020 at 1:14 AM Robert Ramey via Boost <
> [hidden email]> wrote:
>
> > On 4/14/20 5:52 AM, David Bellot via Boost wrote:
> > > Hi,
> > >
> > > The registration for organization is now open.
> > > If anyone is interested in managing this project and wish to talk about
> > > now, please let me know. I've got some experience now managing the
> Google
> > > Summer of Code and can help with GSoD too.
> > >
> > > Cheers,
> > > David
> > >
> > > _______________________________________________
> > > Unsubscribe & other changes:
> > http://lists.boost.org/mailman/listinfo.cgi/boost
> > >
> >
> > Has anyone manifested interest in actually writing documentation?  If
> > so, for what software?
> >
> > Robert Ramey
> >
> > _______________________________________________
> > Unsubscribe & other changes:
> > http://lists.boost.org/mailman/listinfo.cgi/boost
> >
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
I'd be grateful is someone would take date-time docs in boost-book xml and
translate them into quickbook.  That could be a tool that it looks like
several other library maintainers might be interested in.

On Sun, Apr 19, 2020 at 6:39 AM Cem Bassoy via Boost <[hidden email]>
wrote:

> Hi Robert,
>
> good question. I can only speak for Boost/numeric/ublas.
> Our documentation needs to be ported from pure html to rst code with
> sphinx.
> I would like to add examples and doxygen gegenerated reference section.
>
> Best,
> Cem
>
> Am Sa., 18. Apr. 2020 um 23:41 Uhr schrieb David Bellot via Boost <
> [hidden email]>:
>
> > so far, Damian and Cem are interested to help on this project.
> >
> > On Sun, Apr 19, 2020 at 1:14 AM Robert Ramey via Boost <
> > [hidden email]> wrote:
> >
> > > On 4/14/20 5:52 AM, David Bellot via Boost wrote:
> > > > Hi,
> > > >
> > > > The registration for organization is now open.
> > > > If anyone is interested in managing this project and wish to talk
> about
> > > > now, please let me know. I've got some experience now managing the
> > Google
> > > > Summer of Code and can help with GSoD too.
> > > >
> > > > Cheers,
> > > > David
> > > >
> > > > _______________________________________________
> > > > Unsubscribe & other changes:
> > > http://lists.boost.org/mailman/listinfo.cgi/boost
> > > >
> > >
> > > Has anyone manifested interest in actually writing documentation?  If
> > > so, for what software?
> > >
> > > Robert Ramey
> > >
> > > _______________________________________________
> > > Unsubscribe & other changes:
> > > http://lists.boost.org/mailman/listinfo.cgi/boost
> > >
> >
> > _______________________________________________
> > Unsubscribe & other changes:
> > http://lists.boost.org/mailman/listinfo.cgi/boost
> >
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
On 4/19/20 4:29 PM, Jeff Garland via Boost wrote:
> I'd be grateful is someone would take date-time docs in boost-book xml and
> translate them into quickbook.  That could be a tool that it looks like
> several other library maintainers might be interested in.

I had this very issue.  I solved by using a boost book xml GUI editor -
XmlMind.  So every time I update the docs, it's a very simple task.

a) no interaction with b2/boost-build
b) no connection with other cool software which mostly works
c) ability to produce html and/or PDF
d) working with the boost book tool chain which has been working for at
least 15 years.
d) Just all around simpler.

Robert Ramey


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Mon, 20 Apr 2020 at 01:29, Jeff Garland via Boost
<[hidden email]> wrote:
>
> I'd be grateful is someone would take date-time docs in boost-book xml and
> translate them into quickbook.  That could be a tool that it looks like
> several other library maintainers might be interested in.

or to AsciiDoc, I guess.

Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
Mateusz Loskot via Boost <[hidden email]> schrieb am Mo. 20. Apr.
2020 um 10:28:

> On Mon, 20 Apr 2020 at 01:29, Jeff Garland via Boost
> <[hidden email]> wrote:
> >
> > I'd be grateful is someone would take date-time docs in boost-book xml
> and
> > translate them into quickbook.  That could be a tool that it looks like
> > several other library maintainers might be interested in.
>
> or to AsciiDoc, I guess.



Is GIL using AsciiDoc?


>
> Best regards,
> --
> Mateusz Loskot, http://mateusz.loskot.net
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
Sounds a good idea - IMO the best Boost documentation is written in Quickbook (and has reference info using Doxygen Syntax) and an Index.

(but then I would say that wouldn't I  😉)

Paul


> -----Original Message-----
> From: Boost <[hidden email]> On Behalf Of Jeff Garland via Boost
> Sent: 20 April 2020 00:29
> To: Boost Developers List <[hidden email]>
> Cc: Jeff Garland <[hidden email]>
> Subject: Re: [boost] Google Season of Docs
>
> I'd be grateful is someone would take date-time docs in boost-book xml and
> translate them into quickbook.  That could be a tool that it looks like several other
> library maintainers might be interested in.
>
> On Sun, Apr 19, 2020 at 6:39 AM Cem Bassoy via Boost <[hidden email]>
> wrote:
>
> > Hi Robert,
> >
> > good question. I can only speak for Boost/numeric/ublas.
> > Our documentation needs to be ported from pure html to rst code with
> > sphinx.
> > I would like to add examples and doxygen gegenerated reference section.
> >
> > Best,
> > Cem
> >
> > Am Sa., 18. Apr. 2020 um 23:41 Uhr schrieb David Bellot via Boost <
> > [hidden email]>:
> >
> > > so far, Damian and Cem are interested to help on this project.
> > >
> > > On Sun, Apr 19, 2020 at 1:14 AM Robert Ramey via Boost <
> > > [hidden email]> wrote:
> > >
> > > > On 4/14/20 5:52 AM, David Bellot via Boost wrote:
> > > > > Hi,
> > > > >
> > > > > The registration for organization is now open.
> > > > > If anyone is interested in managing this project and wish to
> > > > > talk
> > about
> > > > > now, please let me know. I've got some experience now managing
> > > > > the
> > > Google
> > > > > Summer of Code and can help with GSoD too.
> > > > >
> > > > > Cheers,
> > > > > David
> > > > >
> > > > > _______________________________________________
> > > > > Unsubscribe & other changes:
> > > > http://lists.boost.org/mailman/listinfo.cgi/boost
> > > > >
> > > >
> > > > Has anyone manifested interest in actually writing documentation?
> > > > If so, for what software?
> > > >
> > > > Robert Ramey
> > > >
> > > > _______________________________________________
> > > > Unsubscribe & other changes:
> > > > http://lists.boost.org/mailman/listinfo.cgi/boost
> > > >
> > >
> > > _______________________________________________
> > > Unsubscribe & other changes:
> > > http://lists.boost.org/mailman/listinfo.cgi/boost
> > >
> >
> > _______________________________________________
> > Unsubscribe & other changes:
> > http://lists.boost.org/mailman/listinfo.cgi/boost
> >
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Mon, 20 Apr 2020 at 10:31, Cem Bassoy <[hidden email]> wrote:

> Mateusz Loskot via Boost <[hidden email]> schrieb am Mo. 20. Apr. 2020 um 10:28:
>>
>> On Mon, 20 Apr 2020 at 01:29, Jeff Garland via Boost
>> <[hidden email]> wrote:
>> >
>> > I'd be grateful is someone would take date-time docs in boost-book xml and
>> > translate them into quickbook.  That could be a tool that it looks like
>> > several other library maintainers might be interested in.
>>
>> or to AsciiDoc, I guess.
>
> Is GIL using AsciiDoc?

No, GIL is using reStructuredText and Sphinx,
but if I was migrating today, I'd go for AsciiDoc, I think.

Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
Mateusz Loskot via Boost <[hidden email]> schrieb am Mo. 20. Apr.
2020 um 10:59:

> On Mon, 20 Apr 2020 at 10:31, Cem Bassoy <[hidden email]> wrote:
> > Mateusz Loskot via Boost <[hidden email]> schrieb am Mo. 20.
> Apr. 2020 um 10:28:
> >>
> >> On Mon, 20 Apr 2020 at 01:29, Jeff Garland via Boost
> >> <[hidden email]> wrote:
> >> >
> >> > I'd be grateful is someone would take date-time docs in boost-book
> xml and
> >> > translate them into quickbook.  That could be a tool that it looks
> like
> >> > several other library maintainers might be interested in.
> >>
> >> or to AsciiDoc, I guess.
> >
> > Is GIL using AsciiDoc?
>
> No, GIL is using reStructuredText and Sphinx,
> but if I was migrating today, I'd go for AsciiDoc, I think.


Can you shortly elaborate? I am asking for ublas.


>
> Best regards,
> --
> Mateusz Loskot, http://mateusz.loskot.net
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:

>
> Mateusz Loskot wrote:
>
> > Cem Bassoy wrote:
> > >
> > > Is GIL using AsciiDoc?
> >
> > No, GIL is using reStructuredText and Sphinx,
> > but if I was migrating today, I'd go for AsciiDoc, I think.
>
> Can you shortly elaborate? I am asking for ublas.

If you're interested, we've converted a few Boost library
documentation from HTML to Asciidoc. For example:

- Boost.Endian:
        Now: https://www.boost.org/doc/libs/1_72_0/libs/endian/doc/html/endian.html
        Before: https://www.boost.org/doc/libs/1_70_0/libs/endian/doc/index.html

- Boost.IO:
        Now: https://www.boost.org/doc/libs/master/libs/io/doc/html/io.html
        Before: https://www.boost.org/doc/libs/1_72_0/libs/io/doc/index.html

- Boost.Smart_Ptr:
        Now: https://www.boost.org/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html
        Before:
https://www.boost.org/doc/libs/1_64_0/libs/smart_ptr/smart_ptr.htm

The Asciidoc files and Jamfiles involved in these projects (and others
- e.g. Boost.Mp11, Boost.Variant2, Boost.Assert, Boost.System are all
Asciidoc too) should highlight how straightforward this would be if
you choose to adopt it. The asciidoctor tool is also fairly easy to
run for users to generate this documentation themselves, compared to
Quickbook+Boostbook. I'm told it is simpler and easier to run than
Sphinx too.

Glen

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
On Mon, 20 Apr 2020 at 17:19, Glen Fernandes via Boost
<[hidden email]> wrote:

> On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
> > Mateusz Loskot wrote:
> > > Cem Bassoy wrote:
> > > >
> > > > Is GIL using AsciiDoc?
> > >
> > > No, GIL is using reStructuredText and Sphinx,
> > > but if I was migrating today, I'd go for AsciiDoc, I think.
> >
> > Can you shortly elaborate? I am asking for ublas.
>
> If you're interested, we've converted a few Boost library
> documentation from HTML to Asciidoc.
> [...]
> The asciidoctor tool is also fairly easy to
> run for users to generate this documentation themselves, compared to
> Quickbook+Boostbook. I'm told it is simpler and easier to run than
> Sphinx too.

Thank you Glen.

Cem, my first issue with Sphinx is reST which, and Quickbook too,
I find not as friendly for a human reader as I do find AsciiDoc.
I like Markdown and AsciiDoc feels more like it and offers
semantic features that I'm missing from Markdown.
I also find Python legacies in Sphinx a bit itching
- originally developed for Python, ported to other domains,
while AsciiDoc and its tools feel domain-agnostic.

OTOH, some argue Sphinx is more capable than AsciiDoctor
here I found a good summary, may be outdated though
https://github.com/neovim/neovim/issues/329#issuecomment-56082074

There are some interesting tools for AsciiDoc format, e.g. http://antora.org/

Finally, as Glen explained, some Boost libraries selected AsciiDoc,
so it makes sense to me to follow the crowd to be able to share knowledge
and any tools and infrastructure that appears in future.

Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
 I'd be fine with AsciiDoc as well, but I'd say currently at least
quickbook appears to be a much more frequent choice. The real question for
the thread remains will we have someone do a project to convert xmldocs
into one of the 'plain text' alternatives?

On Mon, Apr 20, 2020 at 8:36 AM Mateusz Loskot via Boost <
[hidden email]> wrote:

> On Mon, 20 Apr 2020 at 17:19, Glen Fernandes via Boost
> <[hidden email]> wrote:
> > On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
> > > Mateusz Loskot wrote:
> > > > Cem Bassoy wrote:
> > > > >
> > > > > Is GIL using AsciiDoc?
> > > >
> > > > No, GIL is using reStructuredText and Sphinx,
> > > > but if I was migrating today, I'd go for AsciiDoc, I think.
> > >
> > > Can you shortly elaborate? I am asking for ublas.
> >
> > If you're interested, we've converted a few Boost library
> > documentation from HTML to Asciidoc.
> > [...]
> > The asciidoctor tool is also fairly easy to
> > run for users to generate this documentation themselves, compared to
> > Quickbook+Boostbook. I'm told it is simpler and easier to run than
> > Sphinx too.
>
> Thank you Glen.
>
> Cem, my first issue with Sphinx is reST which, and Quickbook too,
> I find not as friendly for a human reader as I do find AsciiDoc.
> I like Markdown and AsciiDoc feels more like it and offers
> semantic features that I'm missing from Markdown.
> I also find Python legacies in Sphinx a bit itching
> - originally developed for Python, ported to other domains,
> while AsciiDoc and its tools feel domain-agnostic.
>
> OTOH, some argue Sphinx is more capable than AsciiDoctor
> here I found a good summary, may be outdated though
> https://github.com/neovim/neovim/issues/329#issuecomment-56082074
>
> There are some interesting tools for AsciiDoc format, e.g.
> http://antora.org/
>
> Finally, as Glen explained, some Boost libraries selected AsciiDoc,
> so it makes sense to me to follow the crowd to be able to share knowledge
> and any tools and infrastructure that appears in future.
>
> Best regards,
> --
> Mateusz Loskot, http://mateusz.loskot.net
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
On Mon, Apr 20, 2020 at 12:09 PM Jeff Garland via Boost
<[hidden email]> wrote:
>
>  I'd be fine with AsciiDoc as well, but I'd say currently at least
> quickbook appears to be a much more frequent choice. The real question for
> the thread remains will we have someone do a project to convert xmldocs
> into one of the 'plain text' alternatives?

Sounds like an ideal thing for this Summer of Docs. Do we have a list
of libraries that are still in:
- Plain handwritten HTML
- XML

DateTime, Array, Iostreams, ...

Glen

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
FWIW, I have converted some libraries to Quickbook and found it quite
straightforward to copy and paste plain text paragraphs into a Quickbook section
scaffold structure, and then make layout changes and add headings etc.

You need a general index, and function, class, macro indexes too that are
automatically generated from the Doxygen Syntax comments in the code.

Providing snippets of working examples is the most valuable feature - in the
knowledge that these really work on all platforms.

IOM having lots and lots of examples are the most valuable part of all this.
That's what people want - "How do I ... ? "

By following examples, and seeking advice, it is pretty straight-forward, if
time-consuming.  I believe that the user experience is good.

Paul

 



> -----Original Message-----
> From: Boost <[hidden email]> On Behalf Of Jeff Garland via
Boost
> Sent: 20 April 2020 17:08
> To: Boost Developers List <[hidden email]>
> Cc: Jeff Garland <[hidden email]>
> Subject: Re: [boost] Google Season of Docs
>
>  I'd be fine with AsciiDoc as well, but I'd say currently at least quickbook
appears to
> be a much more frequent choice. The real question for the thread remains will
we

> have someone do a project to convert xmldocs into one of the 'plain text'
> alternatives?
>
> On Mon, Apr 20, 2020 at 8:36 AM Mateusz Loskot via Boost <
> [hidden email]> wrote:
>
> > On Mon, 20 Apr 2020 at 17:19, Glen Fernandes via Boost
> > <[hidden email]> wrote:
> > > On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
> > > > Mateusz Loskot wrote:
> > > > > Cem Bassoy wrote:
> > > > > >
> > > > > > Is GIL using AsciiDoc?
> > > > >
> > > > > No, GIL is using reStructuredText and Sphinx, but if I was
> > > > > migrating today, I'd go for AsciiDoc, I think.
> > > >
> > > > Can you shortly elaborate? I am asking for ublas.
> > >
> > > If you're interested, we've converted a few Boost library
> > > documentation from HTML to Asciidoc.
> > > [...]
> > > The asciidoctor tool is also fairly easy to run for users to
> > > generate this documentation themselves, compared to
> > > Quickbook+Boostbook. I'm told it is simpler and easier to run than
> > > Sphinx too.
> >
> > Thank you Glen.
> >
> > Cem, my first issue with Sphinx is reST which, and Quickbook too, I
> > find not as friendly for a human reader as I do find AsciiDoc.
> > I like Markdown and AsciiDoc feels more like it and offers semantic
> > features that I'm missing from Markdown.
> > I also find Python legacies in Sphinx a bit itching
> > - originally developed for Python, ported to other domains, while
> > AsciiDoc and its tools feel domain-agnostic.
> >
> > OTOH, some argue Sphinx is more capable than AsciiDoctor here I found
> > a good summary, may be outdated though
> > https://github.com/neovim/neovim/issues/329#issuecomment-56082074
> >
> > There are some interesting tools for AsciiDoc format, e.g.
> > http://antora.org/
> >
> > Finally, as Glen explained, some Boost libraries selected AsciiDoc, so
> > it makes sense to me to follow the crowd to be able to share knowledge
> > and any tools and infrastructure that appears in future.
> >
> > Best regards,
> > --
> > Mateusz Loskot, http://mateusz.loskot.net
> >
> > _______________________________________________
> > Unsubscribe & other changes:
> > http://lists.boost.org/mailman/listinfo.cgi/boost
> >
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
Dear Glen,

> On 20. Apr 2020, at 17:18, Glen Fernandes via Boost <[hidden email]> wrote:
>
> On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
>>
>> Mateusz Loskot wrote:
>>
>>> Cem Bassoy wrote:
>>>>
>>>> Is GIL using AsciiDoc?
>>>
>>> No, GIL is using reStructuredText and Sphinx,
>>> but if I was migrating today, I'd go for AsciiDoc, I think.
>>
>> Can you shortly elaborate? I am asking for ublas.
>
> If you're interested, we've converted a few Boost library
> documentation from HTML to Asciidoc. For example:
>
> - Boost.Endian:
>        Now: https://www.boost.org/doc/libs/1_72_0/libs/endian/doc/html/endian.html
>        Before: https://www.boost.org/doc/libs/1_70_0/libs/endian/doc/index.html
>
> - Boost.IO:
>        Now: https://www.boost.org/doc/libs/master/libs/io/doc/html/io.html
>        Before: https://www.boost.org/doc/libs/1_72_0/libs/io/doc/index.html
>
> - Boost.Smart_Ptr:
>        Now: https://www.boost.org/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html
>        Before:
> https://www.boost.org/doc/libs/1_64_0/libs/smart_ptr/smart_ptr.htm
>
> The Asciidoc files and Jamfiles involved in these projects (and others
> - e.g. Boost.Mp11, Boost.Variant2, Boost.Assert, Boost.System are all
> Asciidoc too) should highlight how straightforward this would be if
> you choose to adopt it. The asciidoctor tool is also fairly easy to
> run for users to generate this documentation themselves, compared to
> Quickbook+Boostbook. I'm told it is simpler and easier to run than
> Sphinx too.

thank you mentioning this. I am interested in switching from Quickbook to Asciidoc. I am mostly ok with Quickbook, but it is bothering me very much that I am required to close my sections with [endsect]. That is machine-friendly and not human-friendly. I also like the style for the Asciidoc docs with the TOC on the left.

My main question: I generate my reference with doxygen in xml. The xml code is then post-processed using a Python script. The result is then integrated into my Quickbook docs(*) I quickly checked Jamfiles for the example libraries you mentioned, and none of those seem to have a doxygen-generated reference. How would I combine doxygen and Asciidoc?

Best regards,
Hans

(*) How much annoyed I am by the inability of doxygen to produce a proper reference for a template-heavy lib like Boost.Histogram is another story, but I really don't want to write the reference by hand either and keep it in sync with code changes manually.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Google Season of Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
Am Mo., 20. Apr. 2020 um 17:19 Uhr schrieb Glen Fernandes <
[hidden email]>:

> On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:
> >
> > Mateusz Loskot wrote:
> >
> > > Cem Bassoy wrote:
> > > >
> > > > Is GIL using AsciiDoc?
> > >
> > > No, GIL is using reStructuredText and Sphinx,
> > > but if I was migrating today, I'd go for AsciiDoc, I think.
> >
> > Can you shortly elaborate? I am asking for ublas.
>
> If you're interested, we've converted a few Boost library
> documentation from HTML to Asciidoc. For example:
>
> - Boost.Endian:
>         Now:
> https://www.boost.org/doc/libs/1_72_0/libs/endian/doc/html/endian.html
>         Before:
> https://www.boost.org/doc/libs/1_70_0/libs/endian/doc/index.html
>
> - Boost.IO:
>         Now:
> https://www.boost.org/doc/libs/master/libs/io/doc/html/io.html
>         Before:
> https://www.boost.org/doc/libs/1_72_0/libs/io/doc/index.html
>
> - Boost.Smart_Ptr:
>         Now: https://www.boost.orgsciidoc files and Jamfiles involved in
> these projects (a/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html
> <https://www.boost.org/doc/libs/1_72_0/libs/smart_ptr/doc/html/smart_ptr.html>
>         Before:
> https://www.boost.org/doc/libs/1_64_0/libs/smart_ptr/smart_ptr.htm
>
> The Asciidoc files and Jamfiles involved in these projects (and others
> - e.g. Boost.Mp11, Boost.Variant2, Boost.Assert, Boost.System are all
> Asciidoc too) should highlight how straightforward this would be if
> you choose to adopt it. The asciidoctor tool is also fairly easy to
> run for users to generate this documentation themselves, compared to
> Quickbook+Boostbook. I'm told it is simpler and easier to run than
> Sphinx too.
>

I had a little bit of experience with sphinx using exhale and breathe.
The output generation with the Jamfile seems to be simpler than with Sphinx.

Is there a possibility to integrate doxygen reference like with sphinx
using exhale and breathe?
One could add an extra section for the reference hmtl, but only in the
doxygen style.
Maybe using an external converter.

However, I haven't seen a reference section for Boost.IO/Boost.Endian/etc.
(not needed?)

Thanks,
Cem


>
> Glen
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
123