[
https://issues.apache.org/jira/browse/TS-2446?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13864887#comment-13864887
]
James Peach commented on TS-2446:
---------------------------------
You should always use the explicit directives rather than lower level RST
markup, i.e., {{:ts:cv:}} would always be preferred for configuration
variables. Almost all the rst.ninjs.org errors appear to be due to our custom
directives or the sphinx ones. You can probably get better warnings from the
RTD build logs https://readthedocs.org/builds/trafficserver .
I agree that we should have documentation standards written down somewhere.
Explanations of the custom directives would be very useful as well.
> Document how to document
> ------------------------
>
> Key: TS-2446
> URL: https://issues.apache.org/jira/browse/TS-2446
> Project: Traffic Server
> Issue Type: Improvement
> Components: Documentation
> Reporter: Miles Libbey
> Fix For: Docs
>
>
> Our documentation system has a very large learning curve. Writers need to
> learn reStructured text and Sphinx and our unique conventions/hooks/whatever.
> Without documentation, writers have to view many doc source code to attempt
> to comprehend what those conventions are. Similarly, these conventions
> prevent standard reStructured text from rendering cleanly (for instance,
> http://rst.ninjs.org/ shows tons of errors for any given doc file we have --
> http://rst.ninjs.org/?n=aa8dc0bc3e337df7a2b5e14757debc81&theme=basic).
> Lastly, we should provide explicit, step by step instructions on how to get a
> local version of sphinx up and running that a non developer can follow.
> We need to document:
> - what are all the trafficserver specific hooks/conventions?
> - when should they be used?
> - how they should be used?
> - how to preview a change without pushing to production?
> For instance, Igor noted as part of reviewing
> https://issues.apache.org/jira/browse/TS-2183 :
> "General: all of the CAPSLOCK words should be put in the glossary"
> - how does one mark a term in the doc as having a glossary item?
> - where (what file) would the item's definition go?
> - what is the structure of that definition?
> Some other specific markup that needs explanation:
> :ts:cv:
> ts:const:
> ts:git:
> Similarly, it's also not clear to me when to choose markup like
> `proxy.config.http.server_ports`_ versus :index: vs :ts:cv: vs :ref: etc.
--
This message was sent by Atlassian JIRA
(v6.1.5#6160)
