[prev in list] [next in list] [prev in thread] [next in thread]
List: qgis-developer
Subject: Re: [QGIS-Developer] QGIS Docs: ReStructureText flavour?
From: Alexandre Neto <senhor.neto () gmail ! com>
Date: 2021-03-31 22:10:07
Message-ID: CA+H0G_HpgRL1JM=SA__bt=7iZx69JzVgZOLfgcdHnYtUeFqtxQ () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
Hi,
As far as I remember, sphinx is based/expands "normal" RST introducing new
directives, so it should be normal that some seems to be missing when you
try to parse them using a rst parser.
Alexandre Neto
A quarta, 31/03/2021, 14:11, DelazJ <delazj@gmail.com> escreveu:
> Hi Jonathan,
>
> I can't answer whether there's any particular RST flavour behind. What I
> know is that we rely on Sphinx [0] and most of the rules/syntaxes we use
> are picked from them. The docs guidelines [1] also provide some explanati=
on
> on the choice made.
> So, in the Sphinx docs, you can find :ref: [2] and .. only:: [3]
>
> [0] https://www.sphinx-doc.org/en/master/
> [1] https://docs.qgis.org/3.16/en/docs/documentation_guidelines/index.htm=
l
> [2]
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cr=
oss-referencing-arbitrary-locations
> [3]
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.ht=
ml#directive-only
>
> Hope that clarifies,
> Harrissou
>
> Le mer. 31 mars 2021 =C3=A0 14:21, Jonathan Moules <
> jonathan-lists@lightpear.com> a =C3=A9crit :
>
>> Hi List,
>>
>> What flavour is the RST behind the QGIS docs? There are quite a few
>> things in here that are syntax erroring all the parsers I'm trying and
>> aren't in the basic RST spec either
>> (https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt).
>>
>> For example using ":ref:" for internal hyperlinks when the spec says
>> they should be done like this:
>>
>> https://docutils.sourceforge.io/docs/user/rst/quickref.html#internal-hyp=
erlink-targets
>> (there is no "ref" in the specs). Or the `.. only:: html` that starts
>> some files.
>>
>> I tried looking at the QGIS Docs page but I couldn't see anything about
>> what RST standard the docs should be written to. Where can I find the
>> spec?
>>
>> Cheers,
>>
>> Jonathan
>>
>> _______________________________________________
>> QGIS-Developer mailing list
>> QGIS-Developer@lists.osgeo.org
>> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>>
> _______________________________________________
> QGIS-Developer mailing list
> QGIS-Developer@lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>
[Attachment #5 (text/html)]
<div dir="auto"><div dir="auto">Hi,</div><div dir="auto"><br></div>As far as I \
remember, sphinx is based/expands "normal" RST introducing new directives, \
so it should be normal that some seems to be missing when you try to parse them using \
a rst parser.<div dir="auto"><br></div><div dir="auto">Alexandre \
Neto</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">A \
quarta, 31/03/2021, 14:11, DelazJ <<a href="mailto:delazj@gmail.com" \
target="_blank" rel="noreferrer">delazj@gmail.com</a>> \
escreveu:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 \
.8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>Hi \
Jonathan,</div><div><br></div><div>I can't answer whether there's any \
particular RST flavour behind. What I know is that we rely on Sphinx [0] and most of \
the rules/syntaxes we use are picked from them. The docs guidelines [1] also provide \
some explanation on the choice made.<br></div><div></div><div>So, in the Sphinx docs, \
you can find :ref: [2] and .. only:: [3]</div><div><br></div><div>[0] <a \
href="https://www.sphinx-doc.org/en/master/" rel="noreferrer noreferrer" \
target="_blank">https://www.sphinx-doc.org/en/master/</a></div><div>[1] <a \
href="https://docs.qgis.org/3.16/en/docs/documentation_guidelines/index.html" \
rel="noreferrer noreferrer" \
target="_blank">https://docs.qgis.org/3.16/en/docs/documentation_guidelines/index.html</a></div><div>[2] \
<a href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-arbitrary-locations" \
rel="noreferrer noreferrer" \
target="_blank">https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-arbitrary-locations</a></div><div><div>[3] \
<a href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only" \
rel="noreferrer noreferrer" \
target="_blank">https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only</a></div></div><div><br></div><div>Hope \
that clarifies,</div><div>Harrissou<br></div><br><div class="gmail_quote"><div \
dir="ltr" class="gmail_attr">Le mer. 31 mars 2021 Ã 14:21, Jonathan Moules <<a \
href="mailto:jonathan-lists@lightpear.com" rel="noreferrer noreferrer" \
target="_blank">jonathan-lists@lightpear.com</a>> a écrit :<br></div><blockquote \
class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid \
rgb(204,204,204);padding-left:1ex">Hi List,<br> <br>
What flavour is the RST behind the QGIS docs? There are quite a few <br>
things in here that are syntax erroring all the parsers I'm trying and <br>
aren't in the basic RST spec either <br>
(<a href="https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt" \
rel="noreferrer noreferrer noreferrer" \
target="_blank">https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt</a>).<br>
<br>
For example using ":ref:" for internal hyperlinks when the spec says <br>
they should be done like this: <br>
<a href="https://docutils.sourceforge.io/docs/user/rst/quickref.html#internal-hyperlink-targets" \
rel="noreferrer noreferrer noreferrer" \
target="_blank">https://docutils.sourceforge.io/docs/user/rst/quickref.html#internal-hyperlink-targets</a> \
<br> (there is no "ref" in the specs). Or the `.. only:: html` that starts \
<br> some files.<br>
<br>
I tried looking at the QGIS Docs page but I couldn't see anything about <br>
what RST standard the docs should be written to. Where can I find the spec?<br>
<br>
Cheers,<br>
<br>
Jonathan<br>
<br>
_______________________________________________<br>
QGIS-Developer mailing list<br>
<a href="mailto:QGIS-Developer@lists.osgeo.org" rel="noreferrer noreferrer" \
target="_blank">QGIS-Developer@lists.osgeo.org</a><br> List info: <a \
href="https://lists.osgeo.org/mailman/listinfo/qgis-developer" rel="noreferrer \
noreferrer noreferrer" \
target="_blank">https://lists.osgeo.org/mailman/listinfo/qgis-developer</a><br>
Unsubscribe: <a href="https://lists.osgeo.org/mailman/listinfo/qgis-developer" \
rel="noreferrer noreferrer noreferrer" \
target="_blank">https://lists.osgeo.org/mailman/listinfo/qgis-developer</a><br> \
</blockquote></div></div> _______________________________________________<br>
QGIS-Developer mailing list<br>
<a href="mailto:QGIS-Developer@lists.osgeo.org" rel="noreferrer noreferrer" \
target="_blank">QGIS-Developer@lists.osgeo.org</a><br> List info: <a \
href="https://lists.osgeo.org/mailman/listinfo/qgis-developer" rel="noreferrer \
noreferrer noreferrer" \
target="_blank">https://lists.osgeo.org/mailman/listinfo/qgis-developer</a><br>
Unsubscribe: <a href="https://lists.osgeo.org/mailman/listinfo/qgis-developer" \
rel="noreferrer noreferrer noreferrer" \
target="_blank">https://lists.osgeo.org/mailman/listinfo/qgis-developer</a><br> \
</blockquote></div>
_______________________________________________
QGIS-Developer mailing list
QGIS-Developer@lists.osgeo.org
List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic