Changeset 1013
- Timestamp:
- Jul 13, 2012 6:22:45 PM (11 years ago)
- Location:
- specdomain/trunk/src/specdomain/doc
- Files:
-
- 1 added
- 4 edited
-
howto-build.rst (modified) (2 diffs)
-
howto-configure.rst (modified) (2 diffs)
-
howto-install.rst (modified) (1 diff)
-
test1.png (added)
-
todo.rst (modified) (1 diff)
Legend:
- Unmodified
- Added
- Removed
-
specdomain/trunk/src/specdomain/doc/howto-build.rst
r1007 r1013 5 5 How to Build the Documentation from a Sphinx project 6 6 ==================================================================== 7 8 --tba-- 7 9 8 10 :: … … 23 25 ``build/html/index.html`` 24 26 25 --tba-- 27 Test 28 ===== 29 30 For our testing purposes, we'll document the *aalength.mac* 31 macro file from the :ref:`Install` section. 32 Edit the new file *index.rst* and add this line at line 14. 33 Make sure it lines up at the left in column 1:: 34 35 .. autospecmacro:: ../specdomain/doc/aalength.mac 36 37 Build the HTML documentation:: 38 39 make html 40 41 View the documentation using a web browser such as *firefox*:: 42 43 firefox _build/html/index.html & 44 45 You 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 14 14 files in a separate directory from the SPEC macros. 15 15 Then again, maybe not. 16 17 --tba-- 16 18 17 19 .. index:: ! in-source configuration … … 38 40 ===================================== 39 41 40 :: 42 .. sidebar:: Testing the installation 41 43 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. 43 47 44 .. TODO: Show a blow-by-blow of what this looks like. 48 Make a new sandbox directory to try this out:: 49 50 mkdir /tmp/sandbox 51 cd /tmp/sandbox 52 53 Create 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 45 133 46 134 Configure: Changes to ``conf.py`` 47 135 ===================================== 48 136 49 tba 137 Edit 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 142 If you wish, you can also change the *html_theme* from the 143 *default* to *sphinxdoc* or *agogo* or one of the others. 144 Check the Sphinx documentation for the choices. To change 145 the theme, look on line 97 (or thereabouts) and change:: 146 147 html_theme = 'default' 148 149 to:: 150 151 html_theme = 'sphinxdoc' -
specdomain/trunk/src/specdomain/doc/howto-install.rst
r1007 r1013 7 7 #. download from the subversion repository 8 8 #. install into Python 9 #. test the installation 9 10 10 Requires 11 Requires [#]_ 11 12 * Python 2.7 or greater 12 * Sphinx 1.1. 3 or greater (may work with older versions)13 * Sphinx 1.1.1 or greater 13 14 14 15 Download 15 16 ========== 16 17 17 -tba- 18 Retrieve 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: 18 25 19 26 Install 20 27 ========== 21 28 22 -tba- 29 Continuing from the download above, use the setup tools 30 to install the package somewhere on your PYTHONPATH 31 (you may need admin rights to install into your Python). 32 This 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 15 15 * support the :summary: role to explicitly declare a summary 16 16 * 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.
