[Numpy-svn] r6141 - in trunk/doc: . source source/reference sphinxext

numpy-svn@scip... numpy-svn@scip...
Sat Dec 13 15:02:26 CST 2008


Author: ptvirtan
Date: 2008-12-13 15:02:05 -0600 (Sat, 13 Dec 2008)
New Revision: 6141

Modified:
   trunk/doc/Makefile
   trunk/doc/source/conf.py
   trunk/doc/source/reference/routines.emath.rst
   trunk/doc/source/reference/routines.matlib.rst
   trunk/doc/source/reference/routines.numarray.rst
   trunk/doc/source/reference/routines.oldnumeric.rst
   trunk/doc/sphinxext/numpydoc.py
   trunk/doc/summarize.py
Log:
docs: fix minor issues, support htmlhelp.

- Don't use :members: in automodule; it generates too much
  and not very useful output

- Fix edit links and summarize.py

- Add better htmlhelp build target

- Add upload target

- Fix permissions on make dist

Modified: trunk/doc/Makefile
===================================================================
--- trunk/doc/Makefile	2008-12-13 16:18:04 UTC (rev 6140)
+++ trunk/doc/Makefile	2008-12-13 21:02:05 UTC (rev 6141)
@@ -22,19 +22,30 @@
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
+	@echo "  upload USER=...  to upload results to docs.scipy.org"
 
 clean:
 	-rm -rf build/* source/reference/generated
 
+upload:
+	@test -e build/dist || { echo "make dist is required first"; exit 1; }
+	@test output-is-fine -nt build/dist || { \
+		echo "Review the output in build/dist, and do 'touch output-is-fine' before uploading."; exit 1; }
+	rsync -r -z --delete-after -p build/dist/ $(USER)@docs.scipy.org:/home/docserver/www-root/doc/numpy/
+
 dist: html
 	test -d build/latex || make latex
 	make -C build/latex all-pdf
+	-test -d build/htmlhelp || make htmlhelp-build
 	-rm -rf build/dist
 	cp -r build/html build/dist
 	perl -pi -e 's#^\s*(<li><a href=".*?">NumPy.*?Manual.*?&raquo;</li>)#<li><a href="/">Numpy and Scipy Documentation</a> &raquo;</li>#;' build/dist/*.html build/dist/*/*.html build/dist/*/*/*.html
 	cd build/html && zip -9r ../dist/numpy-html.zip .
-	cp build/latex/*.pdf build/dist
+	cp build/latex/numpy-*.pdf build/dist
+	-cp build/htmlhelp/numpy.chm build/dist
 	cd build/dist && tar czf ../dist.tar.gz *
+	chmod ug=rwX,o=rX -R build/dist
+	find build/dist -type d -print0 | xargs -0r chmod g+s
 
 generate: build/generate-stamp
 build/generate-stamp: $(wildcard source/reference/*.rst)
@@ -67,10 +78,15 @@
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in build/htmlhelp."
 
+htmlhelp-build: htmlhelp build/htmlhelp/numpy.chm
+%.chm: %.hhp
+	-hhc.exe $^
+
 latex: generate
 	mkdir -p build/latex build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
 	python postprocess.py tex build/latex/*.tex
+	perl -pi -e 's/\t(latex.*|pdflatex) (.*)/\t-$$1 -interaction batchmode $$2/' build/latex/Makefile
 	@echo
 	@echo "Build finished; the LaTeX files are in build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \

Modified: trunk/doc/source/conf.py
===================================================================
--- trunk/doc/source/conf.py	2008-12-13 16:18:04 UTC (rev 6140)
+++ trunk/doc/source/conf.py	2008-12-13 21:02:05 UTC (rev 6141)
@@ -21,7 +21,7 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc',
               'phantom_import', 'autosummary', 'sphinx.ext.intersphinx',
-              'sphinx.ext.coverage']
+              'sphinx.ext.coverage', 'only_directives']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -131,7 +131,7 @@
 #html_file_suffix = '.html'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'NumPydoc'
+htmlhelp_basename = 'numpy'
 
 # Pngmath should try to align formulas properly
 pngmath_use_preview = True
@@ -208,7 +208,7 @@
 phantom_import_file = 'dump.xml'
 
 # Edit links
-#numpydoc_edit_link = '`Edit </pydocweb/doc/%(full_name)s/>`__'
+numpydoc_edit_link = '`Edit </numpy/docs/%(full_name)s/>`__'
 
 # -----------------------------------------------------------------------------
 # Coverage checker

Modified: trunk/doc/source/reference/routines.emath.rst
===================================================================
--- trunk/doc/source/reference/routines.emath.rst	2008-12-13 16:18:04 UTC (rev 6140)
+++ trunk/doc/source/reference/routines.emath.rst	2008-12-13 21:02:05 UTC (rev 6141)
@@ -7,4 +7,4 @@
           available after :mod:`numpy` is imported.
 
 .. automodule:: numpy.lib.scimath
-   :members:
+

Modified: trunk/doc/source/reference/routines.matlib.rst
===================================================================
--- trunk/doc/source/reference/routines.matlib.rst	2008-12-13 16:18:04 UTC (rev 6140)
+++ trunk/doc/source/reference/routines.matlib.rst	2008-12-13 21:02:05 UTC (rev 6141)
@@ -8,4 +8,4 @@
 <matrix>` instead of :class:`ndarrays <ndarray>`.
 
 .. automodule:: numpy.matlib
-   :members:
+

Modified: trunk/doc/source/reference/routines.numarray.rst
===================================================================
--- trunk/doc/source/reference/routines.numarray.rst	2008-12-13 16:18:04 UTC (rev 6140)
+++ trunk/doc/source/reference/routines.numarray.rst	2008-12-13 21:02:05 UTC (rev 6141)
@@ -3,4 +3,4 @@
 **********************************************
 
 .. automodule:: numpy.numarray
-   :members:
+

Modified: trunk/doc/source/reference/routines.oldnumeric.rst
===================================================================
--- trunk/doc/source/reference/routines.oldnumeric.rst	2008-12-13 16:18:04 UTC (rev 6140)
+++ trunk/doc/source/reference/routines.oldnumeric.rst	2008-12-13 21:02:05 UTC (rev 6141)
@@ -5,4 +5,4 @@
 .. currentmodule:: numpy
 
 .. automodule:: numpy.oldnumeric
-   :members:
+

Modified: trunk/doc/sphinxext/numpydoc.py
===================================================================
--- trunk/doc/sphinxext/numpydoc.py	2008-12-13 16:18:04 UTC (rev 6140)
+++ trunk/doc/sphinxext/numpydoc.py	2008-12-13 21:02:05 UTC (rev 6141)
@@ -33,8 +33,13 @@
 
     if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \
            obj.__name__:
-        v = dict(full_name=obj.__name__)
-        lines += [''] + (app.config.numpydoc_edit_link % v).split("\n")
+        if hasattr(obj, '__module__'):
+            v = dict(full_name="%s.%s" % (obj.__module__, obj.__name__))
+        else:
+            v = dict(full_name=obj.__name__)
+        lines += ['', '.. htmlonly::', '']
+        lines += ['    %s' % x for x in
+                  (app.config.numpydoc_edit_link % v).split("\n")]
 
     # replace reference numbers so that there are no duplicates
     references = []

Modified: trunk/doc/summarize.py
===================================================================
--- trunk/doc/summarize.py	2008-12-13 16:18:04 UTC (rev 6140)
+++ trunk/doc/summarize.py	2008-12-13 21:02:05 UTC (rev 6141)
@@ -7,10 +7,10 @@
 """
 
 import os, glob, re, sys, inspect, optparse
-sys.path.append(os.path.join(os.path.dirname(__file__), 'ext'))
-from ext.phantom_import import import_phantom_module
+sys.path.append(os.path.join(os.path.dirname(__file__), 'sphinxext'))
+from sphinxext.phantom_import import import_phantom_module
 
-from ext.autosummary_generate import get_documented
+from sphinxext.autosummary_generate import get_documented
 
 CUR_DIR = os.path.dirname(__file__)
 SOURCE_DIR = os.path.join(CUR_DIR, 'source', 'reference')
@@ -56,6 +56,8 @@
 
 def main():
     p = optparse.OptionParser(__doc__)
+    p.add_option("-c", "--columns", action="store", type="int", dest="cols",
+                 default=3, help="Maximum number of columns")
     options, args = p.parse_args()
 
     if len(args) != 0:
@@ -84,13 +86,13 @@
             print "--- %s\n" % filename
         last_filename = filename
         print " ** ", section
-        print format_in_columns(sorted(names))
+        print format_in_columns(sorted(names), options.cols)
         print "\n"
 
     print ""
     print "Undocumented"
     print "============\n"
-    print format_in_columns(sorted(undocumented.keys()))
+    print format_in_columns(sorted(undocumented.keys()), options.cols)
 
 def check_numpy():
     documented = get_documented(glob.glob(SOURCE_DIR + '/*.rst'))
@@ -141,7 +143,7 @@
     
     return undocumented
 
-def format_in_columns(lst):
+def format_in_columns(lst, max_columns):
     """
     Format a list containing strings to a string containing the items
     in columns.
@@ -149,7 +151,9 @@
     lst = map(str, lst)
     col_len = max(map(len, lst)) + 2
     ncols = 80//col_len
-    if ncols == 0:
+    if ncols > max_columns:
+        ncols = max_columns
+    if ncols <= 0:
         ncols = 1
 
     if len(lst) % ncols == 0:



More information about the Numpy-svn mailing list