Merge pull request #83 from RobinD42/docs-add-wx-prefix

Use "wx." prefix in docs, and other docs improvements.

TODO.rst

@@ -82,25 +82,35 @@ check if the the feature is available in wxWidgets or if the stubs should be
 compiled.)
 
 
-Reorganize Sphinx output
-------------------------
+Sphinx tweaks
+-------------
 
-To make it easier for 3rd party tools to find the docs for specific
-classes and methods it would be good to change how the file names for
-the class pages are generated.  Currently it looks like just the
-leading "wx." is missing from the file names.  So that means that
-classes in "core" do not have any package prefix in the filename at
-all.  For example, .../html/Bitmap.html instead of
-.../html/wx.Bitmap.html.  The same holds true for classes in the other
-extension modules in wx, and also wx.lib.
+The big changes are done, but here are some dangling strings that still need
+to be untangled:
 
-    .../html/adv.AnimationCtrl.html
-    .../html/lib.buttons.GenButton.html	
-    etc.
+  * The `chopDescription()` function is not very smart. See if it can be made a
+    little smarter and pull out the first sentence from the docstring instead
+    of ust the first line.
 
-The intra-document anchor links should also have the leading "wx."
-added to them for consistency.
+  * Should we generate property-like docs for MemberVar elements?
 
+  * Convert the main.html page to a ReST file? It would probably make it a
+    little easier to maintain.
+
+  * Turn off full justification of text?
+
+  * Set max width of body sections?  I think it looks a little nicer that way,
+    but we'll need to fix the floating and alignment of the sidebar to do
+    it...
+
+  * Change the column widths of the ReST simple tables, to be about 30/70 instead
+    of 50/50.  This can be done by changing how many '=' are generated for the top
+    and bottom lines of the tables.
+
+  * Move the building of the docs to the Windows build slave so the Windows
+    specific modules will be present for the wxlib build command, so those
+    modules can be documented.
+    
 
 
 Other Dev Stuff
@@ -174,10 +184,10 @@ Other Dev Stuff
     bytes objects, they should probably be string objects. Or not, sip's
     default might be best... See ModuleDef.addGlobalStr if I change my mind.
 
-  * If a function or method has overloads but all but one all ignored then the doc
-    generator should not use the "*args, **kw" form of output and just use the
-    args string of the remaining function or method definition like for those
-    that do not have overloads.  For example, see Window.GetClientSize
+  * If a function or method has overloads but all but one all ignored then the
+    doc generator should not use the "\*args, \*\*kw" form of output and just use
+    the args string of the remaining function or method definition like for
+    those that do not have overloads.  For example, see Window.GetClientSize
 
   * Check gui_scripts entry points.
 

b

@@ -5,11 +5,11 @@
 if [ "$OSTYPE" = "cygwin" ]; then
     PYTHON=`which python.exe`
     echo $PYTHON
-    $PYTHON -u build.py "$@"
+    $PYTHON -u build.py --dev "$@"
 else
     PYTHON=`which python`
     echo $PYTHON
-    $PYTHON -u build.py "$@"
+    $PYTHON -u build.py --dev "$@"
 fi
 
 exit $?

build.py

@@ -863,7 +863,7 @@ def cmd_etg(options, args):
 
     
 def cmd_sphinx(options, args):
-    from sphinxtools.postprocess import SphinxIndexes, MakeHeadings, PostProcess, GenGallery
+    from sphinxtools.postprocess import genIndexes, makeHeadings, postProcess, genGallery
 
     cmdTimer = CommandTimer('sphinx')
     pwd = pushDir(phoenixDir())
@@ -885,8 +885,8 @@ def cmd_sphinx(options, args):
         txt = os.path.join(sphinxDir, os.path.splitext(rstName)[0] + '.txt')
         copyIfNewer(rst, txt)
 
-    SphinxIndexes(sphinxDir)
-    GenGallery()
+    genIndexes(sphinxDir)
+    genGallery()
 
     # Copy the hand-edited top level doc files too
     rstFiles = [os.path.join(phoenixDir(), 'TODO.rst')] + \
@@ -895,7 +895,7 @@ def cmd_sphinx(options, args):
         txt = os.path.join(sphinxDir, os.path.splitext(os.path.basename(rst))[0] + '.txt')
         copyIfNewer(rst, txt)
     
-    MakeHeadings()
+    makeHeadings()
 
     pwd2 = pushDir(sphinxDir)
     buildDir = os.path.join(sphinxDir, 'build')
@@ -904,7 +904,7 @@ def cmd_sphinx(options, args):
     del pwd2
     
     msg('Postprocessing sphinx output...')
-    PostProcess(htmlDir)
+    postProcess(htmlDir)
 
 
 def cmd_wxlib(options, args):
@@ -913,52 +913,25 @@ def cmd_wxlib(options, args):
     cmdTimer = CommandTimer('wx.lib')
     pwd = pushDir(phoenixDir())
 
-    libDir = os.path.join(phoenixDir(), 'wx', 'lib')
+    for wx_pkg in ['lib', 'py', 'tools']:
+        libDir = os.path.join(phoenixDir(), 'wx', wx_pkg)
 
-    if not os.path.isdir(libDir):
-        raise Exception('Missing wx.lib folder in the distribution')
+        if not os.path.isdir(libDir):
+            raise Exception('Missing wx.{} folder in the distribution'.format(wx_pkg))
+
+        init_name = os.path.join(libDir, '__init__.py')
+        import_name = 'wx.{}'.format(wx_pkg)
+
+        ModuleHunter(init_name, import_name, version3)
 
-    init_name = os.path.join(libDir, '__init__.py')
-    import_name = 'lib'
-    version = version3
 
-    ModuleHunter(init_name, import_name, version)
-    
 
 def cmd_wxpy(options, args):
-    from sphinxtools.modulehunter import ModuleHunter
-
-    cmdTimer = CommandTimer('wx.py')
-    pwd = pushDir(phoenixDir())
-
-    libDir = os.path.join(phoenixDir(), 'wx', 'py')
-
-    if not os.path.isdir(libDir):
-        raise Exception('Missing wx.py folder in the distribution')
-
-    init_name = os.path.join(libDir, '__init__.py')
-    import_name = 'py'
-    version = version3
-
-    ModuleHunter(init_name, import_name, version)
+    msg('Command wxpy has been folded into command wxlib.')
 
 
 def cmd_wxtools(options, args):
-    from sphinxtools.modulehunter import ModuleHunter
-
-    cmdTimer = CommandTimer('wx.tools')
-    pwd = pushDir(phoenixDir())
-
-    libDir = os.path.join(phoenixDir(), 'wx', 'tools')
-
-    if not os.path.isdir(libDir):
-        raise Exception('Missing wx.tools folder in the distribution')
-
-    init_name = os.path.join(libDir, '__init__.py')
-    import_name = 'tools'
-    version = version3
-
-    ModuleHunter(init_name, import_name, version)
+    msg('Command wxtools has been folded into command wxlib.')
 
 
 def cmd_docs_bdist(options, args):
@@ -1484,7 +1457,7 @@ def cmd_clean_py(options, args):
     cfg = Config()
     deleteIfExists(getWafBuildBase())
     files = list()
-    for wc in ['*.py', '*.pyc', '*.so', '*.dylib', '*.pyd', '*.pdb', '*.pi']:
+    for wc in ['*.py', '*.pyc', '*.so', '*.dylib', '*.pyd', '*.pdb', '*.pi', '*.pyi']:
         files += glob.glob(opj(cfg.PKGDIR, wc))
     if isWindows:
         msw = getMSWSettings(options)
@@ -1499,7 +1472,6 @@ def cmd_clean_py(options, args):
         cmd_clean_py(options, args)
         options.both = True
 
-
     
 def cmd_clean_sphinx(options, args):
     cmdTimer = CommandTimer('clean_sphinx')
@@ -1508,6 +1480,7 @@ def cmd_clean_sphinx(options, args):
     sphinxDir = opj(phoenixDir(), 'docs', 'sphinx')
          
     globs = [ opj(sphinxDir, '*.txt'),
+              opj(sphinxDir, '*.rst'),
               opj(sphinxDir, '*.inc'),
               opj(sphinxDir, '*.pkl'),
               opj(sphinxDir, '*.lst'),

buildbot/master.cfg

@@ -222,7 +222,7 @@ def makeFactory(port, buildType='buildOnly', pyVer='2.7'):
                         mode=mode, method=method))
 
     if buildType == 'docs':
-        cmd = 'python -u build.py %s setrev dox touch etg sip build wxlib wxtools wxpy ' \
+        cmd = 'python -u build.py %s setrev dox touch etg sip build wxlib ' \
               'sphinx docs_bdist sdist --upload' % pyVer
     else:
         cmd = 'python -u build.py %s %s setrev dox touch etg --nodoc sip build' % (pyVer, clean)

docs/sphinx/_static/css/basic.css

@@ -123,7 +123,7 @@ table.contentstable p.biglink {
 }
 
 a.biglink {
-    font-size: 1.3em;
+    font-size: 1.2em;
 }
 
 span.linkdescr {

docs/sphinx/_static/css/phoenix.css

@@ -88,7 +88,8 @@ div.body h4 {
  */
 
 body { 
-  background-color: rgb(230,230,230);
+    background-color: rgb(230,230,230);
+    font-size: 0.95em;
 }
 
 div.headerimage {
@@ -104,7 +105,7 @@ div.document {
   position: relative;
   margin-left: 240px;
   z-index: 0;
-  top: 50px;
+  top: 30px;
 }
 
 div.sphinxsidebar {
@@ -118,15 +119,26 @@ div.sphinxsidebar {
     height: auto;
     z-index: 1;
     left: 0;
-    top: 50px;
-    bottom: 0;  
+    top: 30px;
+    bottom: 0;    
+}
+
+div#searchbox {
+    margin-top: 30px;
+}
+
+div#sourcelink {
+    position: absolute; 
+    bottom: 0;
+    font-style: italic;
+    font-size: small;
 }
 
 div.related {
     background-image: url('../images/sphinxdocs/navigation.png');
     border-top: 1px solid #ddd;
     border-bottom: 1px solid #ddd;
-    font-size: 1em;
+    font-size: 90%;
     position: fixed;
     line-height: normal;
     position: fixed;
@@ -160,19 +172,21 @@ div.related ul li.right {
     font-size: small;
     float: right;
     margin-right: 5px;
-    margin-top: 0;
 }
 
 div.related ul li#searchbox.right {
     float: right;
     margin-right: 5px;
     margin-top:  7px;
+    font-size: 90%;
 }
+
 div.related ul li a {
     margin: 0;
     padding: 0 5px 0 5px;
     line-height: normal;
     color: #EE9816;
+    font-size: 90%;
 }
 
 div.related ul li.reltitle {
@@ -203,6 +217,18 @@ div.sphinxsidebar a {
   color: #355f7c;
 }
 
+div.section a {
+    color:  #ca7900;
+    font-weight: bold;
+    font-style: normal;
+    font-size: 0.95em;
+    letter-spacing: 0.01em;
+}
+
+div.section a:hover {
+    color: #2491cf;
+}
+
 div.sphinxsidebar ul.want-points {
   list-style: disc;
 }