Merge pull request #1205 from psi29a/sphinx

make local documentation development easier

docs/source/conf.py

@@ -11,9 +11,9 @@
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
-
-import sys
+import glob
 import os
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -21,6 +21,12 @@ import os
 project_root = os.path.abspath('../../')
 sys.path.insert(0, project_root)
 
+
+def insensitive_glob(pattern):
+    def either(c):
+        return '[%s%s]' % (c.lower(), c.upper()) if c.isalpha() else c
+    return glob.glob(''.join(map(either, pattern)))
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -35,17 +41,27 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
-    'breathe',
 ]
 
+try:
+    import breathe
+    extensions.append('breathe')
+except ImportError:
+    print("WARNING: Unable to import breathe, code documentation won't be generated.")
+
 # Where breathe can find the source files
+openmw_path = os.path.join(project_root, "apps", "openmw")
+openmw_sub_dirs = os.walk(openmw_path).next()[1]
+openmw_headers = insensitive_glob(os.path.join(openmw_path, "*.hpp"))
+for dir in openmw_sub_dirs:
+    openmw_headers += insensitive_glob(os.path.join(openmw_path, dir, "*.hpp"))
+
+# massage the headers to get the relative path needed
+openmw_headers = [os.path.relpath(x, openmw_path) for x in openmw_headers]
+
 breathe_projects_source = {
-    "openmw": (project_root+"/apps/openmw", ["engine.hpp",
-    "mwbase/dialoguemanager.hpp", "mwbase/environment.hpp",
-    "mwbase/inputmanager.hpp", "mwbase/journal.hpp", "mwbase/mechanicsmanager.hpp",
-    "mwbase/scriptmanager.hpp", "mwbase/soundmanager.hpp", "mwbase/statemanager.hpp",
-    "mwbase/windowmanager.hpp", "mwbase/world.hpp"])
-    }
+    "openmw": (openmw_path, openmw_headers)
+}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -71,10 +87,16 @@ copyright = u'2016, OpenMW Team'
 # The short X.Y version.
 # The full version, including alpha/beta/rc tags.
 
-from parse_cmake import parsing
-cmake_raw = open(project_root+'/CMakeLists.txt', 'r').read()
-cmake_data = parsing.parse(cmake_raw)
-release = version = int(cmake_data[24][1][1].contents), int(cmake_data[25][1][1].contents), int(cmake_data[26][1][1].contents)
+try:
+    from parse_cmake import parsing
+    cmake_raw = open(project_root+'/CMakeLists.txt', 'r').read()
+    cmake_data = parsing.parse(cmake_raw)
+    release = version = '.'.join([cmake_data[24][1][1].contents,
+                                 cmake_data[25][1][1].contents,
+                                 cmake_data[26][1][1].contents])
+except ImportError:
+    release = "UNRELEASED"
+    print("WARNING: Unable to import parse_cmake, version will be set to: {0}.".format(release))
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -150,7 +172,7 @@ html_theme = 'default'
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static',
-                    'openmw-cs/_static'
+                    'manuals/openmw-cs/_static'
                     ]
 
 # Add any extra paths that contain custom files (such as robots.txt or

docs/source/index.rst

@@ -1,19 +1,18 @@
+Welcome to OpenMW's Documentation!
+==================================
 
-Welcome to OpenMW's documentation!
-=====================================
-
-Components
-----------
+Sections
+--------
 
 .. toctree::
     :maxdepth: 2
 
-    openmw/index
-    openmw-cs/index
-    openmw-mods/index
+    manuals/index
+    reference/index
+    source/index
 
 
-Indices and tables
+Indices and Tables
 ==================
 
 * :ref:`genindex`

docs/source/manuals/index.rst

@@ -0,0 +1,7 @@
+User Manuals
+============
+
+.. toctree::
+    :maxdepth: 2
+
+    openmw-cs/index

docs/source/manuals/openmw-cs/index.rst

@@ -1,5 +1,4 @@
-#####################
-OpenMW CS user manual
+OpenMW CS User Manual
 #####################
 
 The following document is the complete user manual for *OpenMW CS*, the
@@ -9,17 +8,17 @@ modding *The Elder Scrolls III: Morrowind* you should at least read the first
 few chapters to familiarise yourself with the new interface.
 
 .. warning::
-   OpenMW CS is still software in development. The manual does not cover any of
-   its shortcomings, it is written as if everything was working as inteded.
-   Please report any software problems as bugs in the software, not errors in
-   the manual.
+    OpenMW CS is still software in development. The manual does not cover any of
+    its shortcomings, it is written as if everything was working as inteded.
+    Please report any software problems as bugs in the software, not errors in
+    the manual.
 
 .. toctree::
-   :caption: Table of Contents
-   :maxdepth: 2
+    :caption: Table of Contents
+    :maxdepth: 2
 
-   foreword
-   tour
-   files-and-directories
-   starting-dialog
+    foreword
+    tour
+    files-and-directories
+    starting-dialog
 

docs/source/openmw-mods/index.rst

@@ -1,20 +0,0 @@
-########################
-OpenMW Modding Reference
-########################
-
-The following document is the complete reference guide to modifying, or modding, your OpenMW setup. It does not cover content creation itself, only how to alter or add to your OpenMW gameplay experience. To learn more about creating new content for OpenMW, please refer to :doc:`../openmw-cs/index`.
-
-.. warning::
-   OpenMW is still software in development. This manual does not cover any of its shortcomings. It is written as if everything was working as inteded. Please report any software problems as bugs in the software, not errors in the manual.
-
-.. toctree::
-   :caption: Table of Contents
-   :maxdepth: 2
-
-   foreword
-   differences
-   mod-install
-   settings/index
-   fonts
-   convert_bump_mapped_mods
-   paths

docs/source/openmw/index.rst

@@ -1,17 +0,0 @@
-###########################
-OpenMW Source Documentation
-###########################
-
-.. toctree::
-  :maxdepth: 2
-
-  mwbase
-
-.. autodoxygenfile:: engine.hpp
-  :project: openmw
-
-Indices and tables
-==================
-
-* :ref:`genindex`
- * :ref:`search`

docs/source/reference/index.rst

@@ -0,0 +1,7 @@
+Reference Material
+==================
+
+.. toctree::
+    :maxdepth: 2
+
+    modding/index

docs/source/reference/modding/index.rst

@@ -0,0 +1,26 @@
+OpenMW Modding Reference
+########################
+
+The following document is the complete reference guide to modifying, or
+modding, your OpenMW setup. It does not cover content creation itself,
+only how to alter or add to your OpenMW gameplay experience. To learn more
+about creating new content for OpenMW, please refer to
+:doc:`/manuals/openmw-cs/index`.
+
+.. warning::
+    OpenMW is still software in development. This manual does not cover any
+    of its shortcomings. It is written as if everything was working as
+    intended. Please report any software problems as bugs in the software,
+    not errors in the manual.
+
+.. toctree::
+    :caption: Table of Contents
+    :maxdepth: 2
+
+    foreword
+    differences
+    mod-install
+    settings/index
+    font
+    convert_bump_mapped_mods
+    paths

docs/source/reference/modding/settings/camera.rst

@@ -24,7 +24,7 @@ This setting determines whether objects that render to a few pixels or smaller w
 The default value is true. This setting can only be configured by editing the settings configuration file.
 
 small feature culling pixel size
----------------------
+--------------------------------
 
 :Type:		floating point
 :Range:		> 0

docs/source/reference/modding/settings/water.rst

@@ -1,5 +1,5 @@
 Water Settings
-############
+##############
 
 .. note::
 	The settings for the water shader are difficult to describe, but can be seen immediately in the Water tab of the Video panel in the Options menu. Changes there will be saved to these settings. It is suggested to stand on the shore of a moderately broad body of water with trees or other objects on the far shore to test reflection textures, underwater plants in shallow water near by to test refraction textures, and some deep water visible from your location to test deep water visibility.

docs/source/reference/modding/settings/windows.rst

@@ -1,5 +1,5 @@
 Windows Settings
-############
+################
 
 :Type:	floating point
 :Range:	0.0 to 1.0

docs/source/source/index.rst

@@ -0,0 +1,7 @@
+Project Source Documentation
+============================
+
+.. toctree::
+    :maxdepth: 2
+
+    openmw/index

docs/source/source/openmw/index.rst

@@ -0,0 +1,13 @@
+OpenMW Source Documentation
+###########################
+
+.. toctree::
+    :maxdepth: 2
+
+    mwbase
+    mwclass
+    mwdialogue
+    mwgui
+
+.. autodoxygenfile:: engine.hpp
+    :project: openmw

docs/source/source/openmw/mwbase.rst

@@ -1,4 +1,3 @@
-########
 ./mwbase
 ########
 
@@ -31,4 +30,3 @@
 
 .. autodoxygenfile:: mwbase/world.hpp
   :project: openmw
-

docs/source/source/openmw/mwclass.rst

@@ -0,0 +1,68 @@
+./mwclass
+#########
+
+.. autodoxygenfile:: mwclass/activator.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/actor.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/apparatus.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/armor.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/bodypart.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/book.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/classes.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/clothing.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/container.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/creature.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/creaturelevlist.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/ingredient.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/itemlevlist.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/light.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/lockpick.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/misc.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/npc.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/potion.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/probe.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/repair.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/static.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwclass/weapon.hpp
+  :project: openmw

docs/source/source/openmw/mwdialogue.rst

@@ -0,0 +1,32 @@
+./mwdialogue
+############
+
+.. autodoxygenfile:: mwdialogue/dialoguemanagerimp.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwdialogue/filter.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwdialogue/hypertextparser.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwdialogue/journalentry.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwdialogue/journalimp.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwdialogue/keywordsearch.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwdialogue/quest.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwdialogue/scripttest.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwdialogue/selectwrapper.hpp
+  :project: openmw
+
+.. autodoxygenfile:: mwdialogue/topic.hpp
+  :project: openmw

docs/source/source/openmw/mwgui.rst

@@ -0,0 +1,227 @@
+./mwgui
+#######
+
+.. autodoxygenfile:: mwgui/alchemywindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/backgroundimage.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/birth.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/bookpage.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/bookwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/charactercreation.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/class.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/companionitemmodel.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/companionwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/confirmationdialog.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/console.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/container.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/containeritemmodel.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/controllers.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/countdialog.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/cursor.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/debugwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/dialogue.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/draganddrop.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/enchantingdialog.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/exposedwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/formatting.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/hud.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/inventoryitemmodel.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/inventorywindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/itemchargeview.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/itemmodel.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/itemselection.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/itemview.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/itemwidget.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/jailscreen.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/journalbooks.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/journalviewmodel.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/journalwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/layout.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/levelupdialog.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/loadingscreen.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/mainmenu.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/mapwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/merchantrepair.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/messagebox.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/mode.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/pickpocketitemmodel.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/quickkeysmenu.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/race.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/recharge.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/referenceinterface.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/repair.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/review.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/savegamedialog.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/screenfader.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/scrollwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/settingswindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/sortfilteritemmodel.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/soulgemdialog.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/spellbuyingwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/spellcreationdialog.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/spellicons.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/spellmodel.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/spellview.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/spellwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/statswindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/textinput.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/timeadvancer.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/tooltips.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/tradeitemmodel.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/tradewindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/trainingwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/travelwindow.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/videowidget.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/waitdialog.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/widgets.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/windowbase.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/windowmanagerimp.hpp
+    :project: openmw
+
+.. autodoxygenfile:: mwgui/windowpinnablebase.hpp
+    :project: openmw