Changeset 1013


Ignore:
Timestamp:
Jul 13, 2012 6:22:45 PM (10 years ago)
Author:
jemian
Message:

refs #8, add to the HOWTO part

Location:
specdomain/trunk/src/specdomain/doc
Files:
1 added
4 edited

Legend:

Unmodified
Added
Removed
  • specdomain/trunk/src/specdomain/doc/howto-build.rst

    r1007 r1013  
    55How to Build the Documentation from a Sphinx project
    66====================================================================
     7
     8--tba--
    79
    810::
     
    2325        ``build/html/index.html``
    2426
    25 --tba--
     27Test
     28=====
     29
     30For our testing purposes, we'll document the *aalength.mac*
     31macro file from the :ref:`Install` section.
     32Edit the new file *index.rst* and add this line at line 14. 
     33Make sure it lines up at the left in column 1::
     34       
     35        .. autospecmacro:: ../specdomain/doc/aalength.mac
     36
     37Build the HTML documentation::
     38
     39    make html
     40
     41View the documentation using a web browser such as *firefox*::
     42
     43        firefox _build/html/index.html &
     44
     45You should see a page that looks like this, if nothing went wrong.
     46
     47.. figure:: test1.png
     48    :alt: view of aalength.mac HTML documentation
     49
     50    Documentation of the **aalength.mac** file.
  • specdomain/trunk/src/specdomain/doc/howto-configure.rst

    r1007 r1013  
    1414                        files in a separate directory from the SPEC macros. 
    1515                        Then again, maybe not.
     16
     17--tba--
    1618
    1719.. index:: ! in-source configuration
     
    3840=====================================
    3941
    40 ::
     42.. sidebar:: Testing the installation
    4143
    42         sphinx-quickstart
     44        These instructions are written to help you test
     45        if you have installed *specdomain* correctly.
     46        They use an *in-source* configuration.
    4347
    44 .. TODO: Show a blow-by-blow of what this looks like.
     48Make a new sandbox directory to try this out::
     49
     50        mkdir /tmp/sandbox
     51        cd /tmp/sandbox
     52
     53Create a Sphinx configuration in this directory by running ``sphinx-quickstart``:
     54
     55.. code-block:: text
     56    :linenos:
     57   
     58        jemian@como-ubuntu64:/tmp/sandbox$ sphinx-quickstart
     59        Welcome to the Sphinx 1.1.2 quickstart utility.
     60       
     61        Please enter values for the following settings (just press Enter to
     62        accept a default value, if one is given in brackets).
     63       
     64        Enter the root path for documentation.
     65        > Root path for the documentation [.]:
     66       
     67        You have two options for placing the build directory for Sphinx output.
     68        Either, you use a directory "_build" within the root path, or you separate
     69        "source" and "build" directories within the root path.
     70        > Separate source and build directories (y/N) [n]:
     71       
     72        Inside the root directory, two more directories will be created; "_templates"
     73        for custom HTML templates and "_static" for custom stylesheets and other static
     74        files. You can enter another prefix (such as ".") to replace the underscore.
     75        > Name prefix for templates and static dir [_]:
     76       
     77        The project name will occur in several places in the built documentation.
     78        > Project name: sandbox
     79        > Author name(s): sandy
     80       
     81        Sphinx has the notion of a "version" and a "release" for the
     82        software. Each version can have multiple releases. For example, for
     83        Python the version is something like 2.5 or 3.0, while the release is
     84        something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
     85        just set both to the same value.
     86        > Project version: test
     87        > Project release [test]:
     88       
     89        The file name suffix for source files. Commonly, this is either ".txt"
     90        or ".rst".  Only files with this suffix are considered documents.
     91        > Source file suffix [.rst]:
     92       
     93        One document is special in that it is considered the top node of the
     94        "contents tree", that is, it is the root of the hierarchical structure
     95        of the documents. Normally, this is "index", but if your "index"
     96        document is a custom template, you can also set this to another filename.
     97        > Name of your master document (without suffix) [index]:
     98       
     99        Sphinx can also add configuration for epub output:
     100        > Do you want to use the epub builder (y/N) [n]:
     101       
     102        Please indicate if you want to use one of the following Sphinx extensions:
     103        > autodoc: automatically insert docstrings from modules (y/N) [n]: y
     104        > doctest: automatically test code snippets in doctest blocks (y/N) [n]:
     105        > intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
     106        > todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
     107        > coverage: checks for documentation coverage (y/N) [n]:
     108        > pngmath: include math, rendered as PNG images (y/N) [n]:
     109        > mathjax: include math, rendered in the browser by MathJax (y/N) [n]:
     110        > ifconfig: conditional inclusion of content based on config values (y/N) [n]:
     111        > viewcode: include links to the source code of documented Python objects (y/N) [n]: y
     112       
     113        A Makefile and a Windows command file can be generated for you so that you
     114        only have to run e.g. `make html' instead of invoking sphinx-build
     115        directly.
     116        > Create Makefile? (Y/n) [y]:
     117        > Create Windows command file? (Y/n) [y]:
     118       
     119        Creating file ./conf.py.
     120        Creating file ./index.rst.
     121        Creating file ./Makefile.
     122        Creating file ./make.bat.
     123       
     124        Finished: An initial directory structure has been created.
     125       
     126        You should now populate your master file ./index.rst and create other documentation
     127        source files. Use the Makefile to build the docs, like so:
     128           make builder
     129        where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
     130       
     131        jemian@como-ubuntu64:/tmp/sandbox$ 
     132
    45133
    46134Configure: Changes to ``conf.py``
    47135=====================================
    48136
    49 tba
     137Edit the new file *conf.py* and add these two lines to the extensions list after line 28::
     138
     139        # this says ${PYTHONPATH)/sphinxcontrib/specdomain.py must be found
     140        extensions.append('sphinxcontrib.specdomain')
     141
     142If you wish, you can also change the *html_theme* from the
     143*default* to *sphinxdoc* or *agogo* or one of the others.
     144Check the Sphinx documentation for the choices.  To change
     145the theme, look on line 97 (or thereabouts) and change::
     146
     147        html_theme = 'default'
     148
     149to::
     150
     151        html_theme = 'sphinxdoc'
  • specdomain/trunk/src/specdomain/doc/howto-install.rst

    r1007 r1013  
    77#. download from the subversion repository
    88#. install into Python
     9#. test the installation
    910
    10 Requires
     11Requires [#]_
    1112        * Python 2.7 or greater
    12         * Sphinx 1.1.3 or greater (may work with older versions)
     13        * Sphinx 1.1.1 or greater
    1314
    1415Download
    1516==========
    1617
    17 -tba-
     18Retrieve the support package from our subversion repository::
     19
     20   svn co https://subversion.xray.aps.anl.gov/bcdaext/specdomain/trunk/src/specdomain/ /tmp/specdomain
     21
     22.. Any tarballs available?
     23
     24.. _Install:
    1825
    1926Install
    2027==========
    2128
    22 -tba-
     29Continuing from the download above, use the setup tools
     30to install the package somewhere on your PYTHONPATH
     31(you may need admin rights to install into your Python).
     32This command shows how to install into Python's
     33*site-packages* directory::
     34
     35        cd /tmp/specdomain
     36        python setup.py install
     37
     38---------------
     39
     40.. rubric:: Footnotes
     41.. [#] The developer used Python 2.7.2 and Sphinx 1.1.2 while writing this support.
     42                Older versions may work but have not been tested.
  • specdomain/trunk/src/specdomain/doc/todo.rst

    r1009 r1013  
    1515* support the :summary: role to explicitly declare a summary
    1616* cdef argument list not handled yet
    17 * Extract index of macros in each macro file (option to index all symbols in a macro file)
     17* Option to index all symbols in a macro file
     18* allow section headings inside macro declaration docstrings
     19* create a role (or example using a ref) to refer to a macro file from the documentation
     20* produce a custom module index with links and summary lines
Note: See TracChangeset for help on using the changeset viewer.