Re: [Mesa-dev] Proposal: move the Mesa documentation to readthedocs.org

[Nicholas Bishop]

Good questions,

> 1. How can we minimize the effort of maintaining two repositories? (I don't
> think anyone here would support dropping the HTML docs, as they feed into
> the main Mesa website).

I agree that maintaining two repos would be bad, but we don't need to
do that. Sphinx can generate HTML from RST in combination with a style
template to provide the look 'n feel. This is what Read The Docs does:
http://docs.readthedocs.io/en/latest/builds.html#sphinx

For Mesa's website we could either pre-generate the HTML and store it
in the mesa git repo alongside the RST sources, or it could be done in
a separate update-the-website script. I'm not sure how Mesa's website
is currently deployed.

> 2. How easy it is to automate the additional tweaks you mention? Scriptable?

Assuming that RST becomes the canonical source for the HTML it'll be a
one time deal; we use pandoc to automate the initial conversion as
shown in my github repo, then manually fix any formatting issues. I'm
not sure how long it would take, but I'm happy to take on that work if
there's buy-in from the project maintainers.

-Nicholas
___
mesa-dev mailing list
mesa-dev@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/mesa-dev

Re: [Mesa-dev] Proposal: move the Mesa documentation to readthedocs.org

[Rhys Kidd]

On 27 August 2016 at 01:09, Nicholas Bishop  wrote:

> Hi,
>
> I'd like to propose a conversion of Mesa's documentation to
> reStructuredText (RST) and hosting the result on readthedocs.org. The
> intent is to make Mesa's documentation more accessible, searchable, and
> easier to edit.
>
> I put together a quick proof-of-concept here:
>
> http://mesa-docs.readthedocs.io/en/latest/intro.html
>
> (For comparison: http://mesa3d.org/intro.html)
>
> Readthedocs.org essentially renders either Markdown or RST from a git
> repository (or other VCS) into a nice pretty set of HTML pages. (I'm more
> familiar with Markdown than RST, but I saw the Gallium docs are already
> using RST on readthedocs.org.)
>
> Putting the content in RST and on readthedocs.org makes formatting and
> searching easy, and it's a familiar platform for many developers.
>
> For the linked proof-of-concept I used pandoc (http://pandoc.org/) to
> convert all the HTML pages to RST, on top of which I did some minor editing
> to make the table of contents look reasonable. It's by no means a finished
> conversion, but I hope having something to look at can make discussion
> easier. This is all just a few hours work, but of course proofing and
> correcting all the text/formatting would take somewhat longer.
>
> Here's the git repo that readthedocs.org is pulling from:
> https://github.com/nicholasbishop/mesa-docs/tree/master/docs
>
> Thoughts?
>

Hello Nicholas,

Although not a core Mesa developer, I have recently done work on Mesa
documentation.

So FWIW, in my view this is a worthwhile objective to work towards
readthedocs.org formatted documentation. It is clear and well presented. We
also have precedence within this project for using that service, for the
Gallium docs in RST.

Worth considering however:

1. How can we minimize the effort of maintaining two repositories? (I don't
think anyone here would support dropping the HTML docs, as they feed into
the main Mesa website).
2. How easy it is to automate the additional tweaks you mention? Scriptable?

Rhys


>
> -Nicholas
>
>
> ___
> mesa-dev mailing list
> mesa-dev@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/mesa-dev
>
>
___
mesa-dev mailing list
mesa-dev@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/mesa-dev

Re: [Mesa-dev] Proposal: move the Mesa documentation to readthedocs.org

[Vedran Miletić]

On 09/07/2016 07:58 PM, Nicholas Bishop wrote:
> Bump, any interest in this?
> 

In my experience rST is much nicer to write than pure HTML, and I like
how the output looks. Definitive yes on the rST instead of HTML, no
strong opinion on readthedocs.org vs self-hosted.

Regards,
Vedran

-- 
Vedran Miletić
vedran.miletic.net
___
mesa-dev mailing list
mesa-dev@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/mesa-dev

Re: [Mesa-dev] Proposal: move the Mesa documentation to readthedocs.org

[Nicholas Bishop]

Bump, any interest in this?

On Sat, Aug 27, 2016 at 1:09 AM, Nicholas Bishop 
wrote:

> Hi,
>
> I'd like to propose a conversion of Mesa's documentation to
> reStructuredText (RST) and hosting the result on readthedocs.org. The
> intent is to make Mesa's documentation more accessible, searchable, and
> easier to edit.
>
> I put together a quick proof-of-concept here:
>
> http://mesa-docs.readthedocs.io/en/latest/intro.html
>
> (For comparison: http://mesa3d.org/intro.html)
>
> Readthedocs.org essentially renders either Markdown or RST from a git
> repository (or other VCS) into a nice pretty set of HTML pages. (I'm more
> familiar with Markdown than RST, but I saw the Gallium docs are already
> using RST on readthedocs.org.)
>
> Putting the content in RST and on readthedocs.org makes formatting and
> searching easy, and it's a familiar platform for many developers.
>
> For the linked proof-of-concept I used pandoc (http://pandoc.org/) to
> convert all the HTML pages to RST, on top of which I did some minor editing
> to make the table of contents look reasonable. It's by no means a finished
> conversion, but I hope having something to look at can make discussion
> easier. This is all just a few hours work, but of course proofing and
> correcting all the text/formatting would take somewhat longer.
>
> Here's the git repo that readthedocs.org is pulling from:
> https://github.com/nicholasbishop/mesa-docs/tree/master/docs
>
> Thoughts?
>
> -Nicholas
>
>
___
mesa-dev mailing list
mesa-dev@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/mesa-dev

[Mesa-dev] Proposal: move the Mesa documentation to readthedocs.org

[Nicholas Bishop]

Hi,

I'd like to propose a conversion of Mesa's documentation to
reStructuredText (RST) and hosting the result on readthedocs.org. The
intent is to make Mesa's documentation more accessible, searchable, and
easier to edit.

I put together a quick proof-of-concept here:

http://mesa-docs.readthedocs.io/en/latest/intro.html

(For comparison: http://mesa3d.org/intro.html)

Readthedocs.org essentially renders either Markdown or RST from a git
repository (or other VCS) into a nice pretty set of HTML pages. (I'm more
familiar with Markdown than RST, but I saw the Gallium docs are already
using RST on readthedocs.org.)

Putting the content in RST and on readthedocs.org makes formatting and
searching easy, and it's a familiar platform for many developers.

For the linked proof-of-concept I used pandoc (http://pandoc.org/) to
convert all the HTML pages to RST, on top of which I did some minor editing
to make the table of contents look reasonable. It's by no means a finished
conversion, but I hope having something to look at can make discussion
easier. This is all just a few hours work, but of course proofing and
correcting all the text/formatting would take somewhat longer.

Here's the git repo that readthedocs.org is pulling from:
https://github.com/nicholasbishop/mesa-docs/tree/master/docs

Thoughts?

-Nicholas
___
mesa-dev mailing list
mesa-dev@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/mesa-dev