slides.txt

                *** The Sphinx Tutorial ***

                      Brandon Rhodes
                        PyCon 2013
                  Santa Clara, California

-----------------------------------------------------------




 * Please make sure Python is installed on your laptop.
 * Then install Sphinx!  Two approaches:

                   $ pip install sphinx
                         -- OR --
        From the thumb drive "packages/" installing:
            docutils, Pygments, Jinja2, Sphinx





          * Writing documentation

             - Automatic API documentation
             - Hand-crafted API documentation
             - Tutorial introduction
             - Topical guides


          * Deploying documentation

             - Serving as static HTML
             - Hosting on Read The Docs
             - Storing in version control
             - Theming the HTML version








                     Community Hosting
                     -----------------



                    * pythonhosted.org
                    * ReadTheDocs.com









                     pythonhosted.org
                     ----------------


      * Used to be named packages.python.org

      * Inconvenient: requires ZIP file upload









                      ReadTheDocs.com
                      ---------------

    * Popular, well supported, awesome

    * First written at the 2010 Django Dash

      http://www.slideshare.net/ericholscher
        /the-story-and-tech-of-read-the-docs









                Deploying to Read the Docs




                 (A story, in four images)











     https://brandons-sphinx-tutorial.readthedocs.org/










            Staying up to date on Read the Docs




     (A story, in two lines of code and three images)









           Create a tag in your version control



            $ git tag -a v0.1 -m 'Tagged v0.1'
            $ git push --tags










                     NOTHING HAPPENED




            I had forgotten the service hook!












                    Then: RTD Admin
                        » Versions
                        » Choose Active Versions








                      Version Control
                      ---------------



         - Semantic newlines can keep diffs simple
           See my blog post "Semantic Linefeeds"









                          Theming
                          -------



               * Choosing a different theme
               * Customizing a theme
               * Taking control of your own












Local variables:
 mode:text
 mode:page
 fill-column:59
End: