Changeset 4213 for trunk/docs


Ignore:
Timestamp:
Dec 19, 2019 11:04:03 PM (3 years ago)
Author:
toby
Message:

multiple small changes to allow docs build under 3.x

Location:
trunk/docs
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/docs/Makefile

    r2027 r4213  
    1 # Makefile for Sphinx documentation
     1# Minimal makefile for Sphinx documentation
    22#
    33
    4 # You can set these variables from the command line.
    5 SPHINXOPTS    =
    6 SPHINXBUILD   = sphinx-build
    7 PAPER         =
     4# You can set these variables from the command line, and also
     5# from the environment for the first two.
     6SPHINXOPTS    ?=
     7SPHINXBUILD   ?= sphinx-build
     8SOURCEDIR     = source
    89BUILDDIR      = build
    910
    10 # Internal variables.
    11 PAPEROPT_a4     = -D latex_paper_size=a4
    12 PAPEROPT_letter = -D latex_paper_size=letter
    13 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
    14 # the i18n builder cannot share the environment and doctrees with the others
    15 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
     11# Put it first so that "make" without argument is like "make help".
     12help:
     13        @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
    1614
    17 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
     15.PHONY: help Makefile
    1816
    19 help:
    20         @echo "Please use \`make <target>' where <target> is one of"
    21         @echo "  html       to make standalone HTML files"
    22         @echo "  dirhtml    to make HTML files named index.html in directories"
    23         @echo "  singlehtml to make a single large HTML file"
    24         @echo "  pickle     to make pickle files"
    25         @echo "  json       to make JSON files"
    26         @echo "  htmlhelp   to make HTML files and a HTML help project"
    27         @echo "  qthelp     to make HTML files and a qthelp project"
    28         @echo "  devhelp    to make HTML files and a Devhelp project"
    29         @echo "  epub       to make an epub"
    30         @echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
    31         @echo "  latexpdf   to make LaTeX files and run them through pdflatex"
    32         @echo "  text       to make text files"
    33         @echo "  man        to make manual pages"
    34         @echo "  texinfo    to make Texinfo files"
    35         @echo "  info       to make Texinfo files and run them through makeinfo"
    36         @echo "  gettext    to make PO message catalogs"
    37         @echo "  changes    to make an overview of all changed/added/deprecated items"
    38         @echo "  linkcheck  to check all external links for integrity"
    39         @echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
    40 
    41 clean:
    42         #-rm -rf $(BUILDDIR)/*
    43         rm $(BUILDDIR)/doctrees/* $(BUILDDIR)/html/*.html $(BUILDDIR)/html/*.js $(BUILDDIR)/html/*/*.html
    44 
    45 html:
    46         $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
    47         @echo
    48         @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
    49 
    50 dirhtml:
    51         $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
    52         @echo
    53         @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
    54 
    55 singlehtml:
    56         $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
    57         @echo
    58         @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
    59 
    60 pickle:
    61         $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
    62         @echo
    63         @echo "Build finished; now you can process the pickle files."
    64 
    65 json:
    66         $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
    67         @echo
    68         @echo "Build finished; now you can process the JSON files."
    69 
    70 htmlhelp:
    71         $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
    72         @echo
    73         @echo "Build finished; now you can run HTML Help Workshop with the" \
    74               ".hhp project file in $(BUILDDIR)/htmlhelp."
    75 
    76 qthelp:
    77         $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
    78         @echo
    79         @echo "Build finished; now you can run "qcollectiongenerator" with the" \
    80               ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
    81         @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/EPICSPythonSPECmotor.qhcp"
    82         @echo "To view the help file:"
    83         @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/EPICSPythonSPECmotor.qhc"
    84 
    85 devhelp:
    86         $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
    87         @echo
    88         @echo "Build finished."
    89         @echo "To view the help file:"
    90         @echo "# mkdir -p $$HOME/.local/share/devhelp/EPICSPythonSPECmotor"
    91         @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/EPICSPythonSPECmotor"
    92         @echo "# devhelp"
    93 
    94 epub:
    95         $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
    96         @echo
    97         @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
    98 
    99 latex:
    100         $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
    101         @echo
    102         @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
    103         @echo "Run \`make' in that directory to run these through (pdf)latex" \
    104               "(use \`make latexpdf' here to do that automatically)."
    105 
    106 latexpdf:
    107         $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
    108         @echo "Running LaTeX files through pdflatex..."
    109         $(MAKE) -C $(BUILDDIR)/latex all-pdf
    110         @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
    111 
    112 text:
    113         $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
    114         @echo
    115         @echo "Build finished. The text files are in $(BUILDDIR)/text."
    116 
    117 man:
    118         $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
    119         @echo
    120         @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
    121 
    122 texinfo:
    123         $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
    124         @echo
    125         @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
    126         @echo "Run \`make' in that directory to run these through makeinfo" \
    127               "(use \`make info' here to do that automatically)."
    128 
    129 info:
    130         $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
    131         @echo "Running Texinfo files through makeinfo..."
    132         make -C $(BUILDDIR)/texinfo info
    133         @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
    134 
    135 gettext:
    136         $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
    137         @echo
    138         @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
    139 
    140 changes:
    141         $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
    142         @echo
    143         @echo "The overview file is in $(BUILDDIR)/changes."
    144 
    145 linkcheck:
    146         $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
    147         @echo
    148         @echo "Link check complete; look for any errors in the above output " \
    149               "or in $(BUILDDIR)/linkcheck/output.txt."
    150 
    151 doctest:
    152         $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
    153         @echo "Testing of doctests in the sources finished, look at the " \
    154               "results in $(BUILDDIR)/doctest/output.txt."
     17# Catch-all target: route all unknown targets to Sphinx using the new
     18# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
     19%: Makefile
     20        @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

  • trunk/docs/make.bat

    r2027 r4213  
    11@ECHO OFF
     2
     3pushd %~dp0
    24
    35REM Command file for Sphinx documentation
    … …  
    68        set SPHINXBUILD=sphinx-build
    79)
     10set SOURCEDIR=source
    811set BUILDDIR=build
    9 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
    10 if NOT "%PAPER%" == "" (
    11         set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
    12 )
    1312
    1413if "%1" == "" goto help
    1514
    16 if "%1" == "help" (
    17         :help
    18         echo.Please use `make ^<target^>` where ^<target^> is one of
    19         echo.  html       to make standalone HTML files
    20         echo.  dirhtml    to make HTML files named index.html in directories
    21         echo.  singlehtml to make a single large HTML file
    22         echo.  pickle     to make pickle files
    23         echo.  json       to make JSON files
    24         echo.  htmlhelp   to make HTML files and a HTML help project
    25         echo.  qthelp     to make HTML files and a qthelp project
    26         echo.  devhelp    to make HTML files and a Devhelp project
    27         echo.  epub       to make an epub
    28         echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
    29         echo.  text       to make text files
    30         echo.  man        to make manual pages
    31         echo.  changes    to make an overview over all changed/added/deprecated items
    32         echo.  linkcheck  to check all external links for integrity
    33         echo.  doctest    to run all doctests embedded in the documentation if enabled
    34         goto end
     15%SPHINXBUILD% >NUL 2>NUL
     16if errorlevel 9009 (
     17        echo.
     18        echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
     19        echo.installed, then set the SPHINXBUILD environment variable to point
     20        echo.to the full path of the 'sphinx-build' executable. Alternatively you
     21        echo.may add the Sphinx directory to PATH.
     22        echo.
     23        echo.If you don't have Sphinx installed, grab it from
     24        echo.http://sphinx-doc.org/
     25        exit /b 1
    3526)
    3627
    37 if "%1" == "clean" (
    38         for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
    39         del /q /s %BUILDDIR%\*
    40         goto end
    41 )
     28%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
     29goto end
    4230
    43 if "%1" == "html" (
    44         %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
    45         echo.
    46         echo.Build finished. The HTML pages are in %BUILDDIR%/html.
    47         goto end
    48 )
    49 
    50 if "%1" == "dirhtml" (
    51         %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
    52         echo.
    53         echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
    54         goto end
    55 )
    56 
    57 if "%1" == "singlehtml" (
    58         %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
    59         echo.
    60         echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
    61         goto end
    62 )
    63 
    64 if "%1" == "pickle" (
    65         %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
    66         echo.
    67         echo.Build finished; now you can process the pickle files.
    68         goto end
    69 )
    70 
    71 if "%1" == "json" (
    72         %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
    73         echo.
    74         echo.Build finished; now you can process the JSON files.
    75         goto end
    76 )
    77 
    78 if "%1" == "htmlhelp" (
    79         %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
    80         echo.
    81         echo.Build finished; now you can run HTML Help Workshop with the ^
    82 .hhp project file in %BUILDDIR%/htmlhelp.
    83         goto end
    84 )
    85 
    86 if "%1" == "qthelp" (
    87         %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
    88         echo.
    89         echo.Build finished; now you can run "qcollectiongenerator" with the ^
    90 .qhcp project file in %BUILDDIR%/qthelp, like this:
    91         echo.^> qcollectiongenerator %BUILDDIR%\qthelp\GeneralStructureAnalysisSystem-II.qhcp
    92         echo.To view the help file:
    93         echo.^> assistant -collectionFile %BUILDDIR%\qthelp\GeneralStructureAnalysisSystem-II.ghc
    94         goto end
    95 )
    96 
    97 if "%1" == "devhelp" (
    98         %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
    99         echo.
    100         echo.Build finished.
    101         goto end
    102 )
    103 
    104 if "%1" == "epub" (
    105         %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
    106         echo.
    107         echo.Build finished. The epub file is in %BUILDDIR%/epub.
    108         goto end
    109 )
    110 
    111 if "%1" == "latex" (
    112         %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
    113         echo.
    114         echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
    115         goto end
    116 )
    117 
    118 if "%1" == "text" (
    119         %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
    120         echo.
    121         echo.Build finished. The text files are in %BUILDDIR%/text.
    122         goto end
    123 )
    124 
    125 if "%1" == "man" (
    126         %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
    127         echo.
    128         echo.Build finished. The manual pages are in %BUILDDIR%/man.
    129         goto end
    130 )
    131 
    132 if "%1" == "changes" (
    133         %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
    134         echo.
    135         echo.The overview file is in %BUILDDIR%/changes.
    136         goto end
    137 )
    138 
    139 if "%1" == "linkcheck" (
    140         %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
    141         echo.
    142         echo.Link check complete; look for any errors in the above output ^
    143 or in %BUILDDIR%/linkcheck/output.txt.
    144         goto end
    145 )
    146 
    147 if "%1" == "doctest" (
    148         %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
    149         echo.
    150         echo.Testing of doctests in the sources finished, look at the ^
    151 results in %BUILDDIR%/doctest/output.txt.
    152         goto end
    153 )
     31:help
     32%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
    15433
    15534:end
     35popd

  • trunk/docs/source/conf.py

    r4205 r4213  
    1212
    1313import sys, os
    14 # set up dummy packages for misc imports not on readthedocs
    15 from mock import Mock as MagicMock
    16 class wx(MagicMock):
    17     #@classmethod
    18     #def __getattr__(cls, name):
    19     #    return wx()
    20     Frame = Menu = Panel = Dialog = CheckBox = Choice = ComboBox = object
    21     Button = PyValidator = TextCtrl = TreeCtrl = object
    22     DEFAULT_DIALOG_STYLE = RESIZE_BORDER = CENTRE = OK = CANCEL = True
    23     ID_ANY = -1
    24     def __getitem__(self,*args):
    25         return '3.0.0'
    26     class grid(object):
    27         PyGridTableBase = PyGridCellEditor = Grid = object
    28     class html(object):
    29         HtmlWindow = object
    30     class aui(MagicMock):
    31         AuiNotebook = HtmlWindow = object
    32     class lib(MagicMock):
    33         class scrolledpanel(MagicMock):
    34             ScrolledPanel = object
    35         class gridmovers(MagicMock): pass
    36         class colourselect(MagicMock): pass
    37         class resizewidget(MagicMock): pass
    38         class mixins(MagicMock):
    39             class listctrl(MagicMock):
    40                 ListCtrlAutoWidthMixin = object
    41                 TextEditMixin = object
    42 
    43 sys.modules.update({'wx':wx(),
    44     'wx.aui':wx.aui(),
    45     'wx.html':wx.html(),
    46         'wx.grid':wx.grid(),
    47         'wx.lib':wx.lib(),
    48         'wx.wizard':wx.grid(),
    49         'wx.glcanvas':wx.lib(),
    50         'wx.lib.scrolledpanel':wx.lib.scrolledpanel(),
    51         'wx.lib.gridmovers':wx.lib.gridmovers(),
    52         'wx.lib.colourselect':wx.lib.gridmovers(),
    53         'wx.lib.resizewidget':wx.lib.resizewidget(),
    54         'wx.lib.mixins':wx.lib.mixins(),
    55         'wx.lib.mixins.listctrl':wx.lib.mixins.listctrl()})
    56 wx.aui.AUI_NB_TOP = 0
    57 wx.aui.AUI_NB_SCROLL_BUTTONS = 0
    58 
    59 class numpy(MagicMock):
    60     pi = 3.0
    61     def log(self,*args): return 0
    62     def sqrt(self,*args): return 1
    63     class ma(MagicMock):pass
    64     class linalg(MagicMock):pass
    65 sys.modules.update({'numpy':numpy()})
    66 sys.modules.update({'numpy.ma':numpy.ma()})
    67 sys.modules.update({'numpy.linalg':numpy.linalg()})
    68 sys.modules.update({'numpy.fft':numpy.linalg()})
    69 
    70 class scipy(MagicMock):
    71     class optimize(MagicMock):pass
    72 sys.modules.update({'scipy':scipy()})
    73 sys.modules.update({'scipy.optimize':scipy.optimize()})
    74 sys.modules.update({'scipy.stats':scipy.optimize()})
    75 sys.modules.update({'scipy.interpolate':scipy.optimize()})
    76 sys.modules.update({'scipy.special':scipy.optimize()})
    77 sys.modules.update({'scipy.misc':scipy.optimize()})
    78 sys.modules.update({'scipy.signal':scipy.optimize()})
    79 sys.modules.update({'scipy.cluster':scipy.optimize()})
    80 sys.modules.update({'scipy.cluster.vq':scipy.optimize()})
    81 
    82 class OpenGL(MagicMock):
    83     class GL(MagicMock):pass
    84     class GLU(MagicMock):pass
    85 sys.modules.update({'OpenGL':OpenGL()})
    86 sys.modules.update({'OpenGL.GL':OpenGL.GL()})
    87 sys.modules.update({'OpenGL.GLU':OpenGL.GLU()})
    88 sys.modules.update({'OpenGL.GLE':OpenGL.GL()})
    89 
    90 class Mock(MagicMock):
    91     @classmethod
    92     def __getattr__(cls, name):
    93         return Mock()
    94 
    95 MOCK_MODULES = [
    96                 'pypowder', 'pyspg', 'pytexture', 'polymask', 'fellipse',
    97                 'matplotlib', 'matplotlib.backends', 'matplotlib.backends.backend_wx',
    98                 'matplotlib.colors',
    99                 'matplotlib.backends.backend_wxagg','pylab','matplotlib.collections',
    100                 'mpl_toolkits', 'mpl_toolkits.mplot3d', 'mpl_toolkits.mplot3d.axes3d',
    101                 'winreg','unpack_cbf','h5py'
    102                 ]
    103 sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
    10414
    10515# If extensions (or modules to document with autodoc) are in another directory,
    … …  
    11121sys.path.insert(1, os.path.abspath(os.path.join('..', '..','imports')))
    11222#print(sys.path)
    113 # import all files to set version number
     23# scan all files to get version number
    11424import glob
    115 for fil in glob.glob(os.path.abspath(os.path.join('..', '..','*.py'))):
    116     pkg = os.path.splitext(os.path.split(fil)[1])[0]
     25version = 0
     26for fil in (glob.glob(os.path.abspath(os.path.join('..', '..','*.py')))+
     27    glob.glob(os.path.abspath(os.path.join('..', '..','exports','*.py')))+
     28    glob.glob(os.path.abspath(os.path.join('..', '..','imports','*.py')))):
     29    fp = open(fil,'r')
     30    c = fp.read()
     31    fp.close()
     32    s = c.find('SetVersionNumber')
     33    if s<0: continue
     34    if c.find('$Revision:',s,s+50)<0: continue
    11735    try:
    118         exec('import '+pkg)
     36        v = int(c[c.find('(',s,s+40):c.find(')',s,s+50)].split()[1])
     37        version = max(version,v)
    11938    except:
    12039        pass
    121 import GSASIIpath
    122 version = GSASIIpath.GetVersionNumber()
    12340print('Found highest version as {}'.format(version))
    12441# -- General configuration -----------------------------------------------------
    … …  
    351268# How to display URL addresses: 'footnote', 'no', or 'inline'.
    352269#texinfo_show_urls = 'footnote'
     270
     271# set up dummy packages for misc imports not on readthedocs
     272autodoc_mock_imports = "wx numpy scipy matplotlib pillow OpenGL h5py".split()
Note: See TracChangeset for help on using the changeset viewer.