[tahoe-lafs-trac-stream] [tahoe-lafs] #2102: generate docs with sphinx

[tahoe-lafs]

#2102: generate docs with sphinx
-------------------------------+--------------------------------
     Reporter:  zooko          |      Owner:  zooko
         Type:  enhancement    |     Status:  new
     Priority:  normal         |  Milestone:  soon (release n/a)
    Component:  documentation  |    Version:  1.10.0
   Resolution:                 |   Keywords:  docs
Launchpad Bug:                 |
-------------------------------+--------------------------------

Comment (by Novacha):

 What you will want to use is the {{{:doc:}}} directive (At [http://sphinx-
 doc.org/markup/inline.html#role-doc]). You will want to replace the
 following

 {{{
 To use Tahoe-LAFS, please see quickstart.rst_.
 }}}

 With

 {{{
 To use Tahoe-LAFS, please see :doc:`quickstart`
 }}}

 You can also name the link what you want

 {{{
 To use Tahoe-LAFS, please see :doc:`the quickstart guide <quickstart>`
 }}}

 Though you can do this, the files you reference '''MUST''' be included in
 a toctree so that sphinx knows the hierarch of the file. It is not good
 enough just to reference it like this (and the sphinx builder will throw
 errors if this is the case). You can create a hidden toctree on the front
 page to include all these files.

 The syntax in the line below is something that I have not seen before, and
 I do not believe it is a valid way of using labels.

 {{{
  .. _quickstart.rst: quickstart.rst
 }}}

 The solution above with the {{{:doc:}}} directive is the way to go with
 all the links that are formatted this way. You could also place labels at
 the top of sections and files (such as putting {{{.. _quickstart:}}} at
 the top of the quickstart.rst file and referencing it like
 {{{:ref:`quickstart`}}}). The documentation for this method can be found
 at [http://sphinx-doc.org/markup/inline.html#role-ref]

-- 
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2102#comment:5>
tahoe-lafs <https://tahoe-lafs.org>
secure decentralized storage