Merge pull request #64 from thehajime/readthedoc

doc infra update: generate doxygen on readthedocs.io servers

Author: thehajime

README.md

@@ -1,4 +1,5 @@
 [![Build status](https://circleci.com/gh/direct-code-execution/ns-3-dce.svg?style=shield&circle-token=a9cf0c7e5e7a1d1a7ff2e2e5b341706fba3ccfb2)](https://circleci.com/gh/direct-code-execution/ns-3-dce)
+[![Documentation Status](https://readthedocs.org/projects/ns-3-dce/badge/?version=latest)](http://ns-3-dce.readthedocs.io/en/latest/?badge=latest)
 [![License](https://img.shields.io/badge/license-GPL-brightgreen.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
 
 What is Direct Code Execution (DCE) ?

doc/doxygen.conf

@@ -32,7 +32,7 @@ PROJECT_NAME           = "ns-3-dce"
 # This could be handy for archiving the generated documentation or
 # if some version control system is used.
 
-PROJECT_NUMBER         = "1.9"
+PROJECT_NUMBER         = DCE_VERSION
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer
@@ -45,7 +45,7 @@ PROJECT_BRIEF          = "A Direct Code Execution for ns-3 Network Simulator"
 # exceed 55 pixels and the maximum width should not exceed 200 pixels.
 # Doxygen will copy the logo to the output directory.
 
-PROJECT_LOGO           = ./doc/ns3_html_theme/static/ns-3-inverted-notext-small.png
+PROJECT_LOGO           =
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
 # base path where the generated documentation will be put.
@@ -321,22 +321,6 @@ INLINE_SIMPLE_STRUCTS  = NO
 
 TYPEDEF_HIDES_STRUCT   = YES
 
-# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to
-# determine which symbols to keep in memory and which to flush to disk.
-# When the cache is full, less often used symbols will be written to disk.
-# For small to medium size projects (<1000 input files) the default value is
-# probably good enough. For larger projects a too small cache size can cause
-# doxygen to be busy swapping symbols to and from disk most of the time
-# causing a significant performance penalty.
-# If the system has enough physical memory increasing the cache will improve the
-# performance by keeping more symbols in memory. Note that the value works on
-# a logarithmic scale so increasing the size by one will roughly double the
-# memory usage. The cache size is given by this formula:
-# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0,
-# corresponding to a cache size of 2^16 = 65536 symbols.
-
-SYMBOL_CACHE_SIZE      = 0
-
 # Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be
 # set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given
 # their name and scope. Since this can be an expensive process and often the
@@ -769,7 +753,7 @@ EXAMPLE_RECURSIVE      = NO
 # directories that contain image that are included in the documentation (see
 # the \image command).
 
-IMAGE_PATH             = doc/ns3_html_theme/static
+IMAGE_PATH             =
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -918,13 +902,13 @@ HTML_FILE_EXTENSION    = .html
 # have to redo this when upgrading to a newer version of doxygen or when
 # changing the value of configuration settings such as GENERATE_TREEVIEW!
 
-HTML_HEADER            = doc/ns3_html_theme/ns3_doxy_header.html
+HTML_HEADER            =
 
 # The HTML_FOOTER tag can be used to specify a personal HTML footer for
 # each generated HTML page. If it is left blank doxygen will generate a
 # standard footer.
 
-HTML_FOOTER            = doc/ns3_html_theme/ns3_doxy_footer.html
+HTML_FOOTER            =
 
 # The HTML_STYLESHEET tag can be used to specify a user-defined cascading
 # style sheet that is used by each HTML page. It can be used to
@@ -933,7 +917,7 @@ HTML_FOOTER            = doc/ns3_html_theme/ns3_doxy_footer.html
 # the style sheet file to the HTML output directory, so don't put your own
 # style sheet in the HTML output directory as well, or it will be erased!
 
-HTML_STYLESHEET        = doc/ns3_html_theme/static/ns3_stylesheet.css
+HTML_STYLESHEET        =
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -942,14 +926,7 @@ HTML_STYLESHEET        = doc/ns3_html_theme/static/ns3_stylesheet.css
 # files. In the HTML_STYLESHEET file, use the file name only. Also note that
 # the files will be copied as-is; there are no commands or markers available.
 
-HTML_EXTRA_FILES       = doc/ns3_html_theme/static/doxygen.css \
-                         doc/ns3_html_theme/static/bar-top.png \
-                         doc/ns3_html_theme/static/drop-down-menu.js \
-                         doc/ns3_html_theme/static/favicon.ico \
-                         doc/ns3_html_theme/static/menu-bgr-400.png \
-                         doc/ns3_html_theme/static/ns3_version.js \
-                         doc/ns3_html_theme/static/ns3_links.js \
-                         doc/ns3_html_theme/static/ver.png
+HTML_EXTRA_FILES       =
 
 # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output.
 # Doxygen will adjust the colors in the style sheet and background images
@@ -1435,18 +1412,6 @@ GENERATE_XML           = NO
 
 XML_OUTPUT             = xml
 
-# The XML_SCHEMA tag can be used to specify an XML schema,
-# which can be used by a validating XML parser to check the
-# syntax of the XML files.
-
-XML_SCHEMA             =
-
-# The XML_DTD tag can be used to specify an XML DTD,
-# which can be used by a validating XML parser to check the
-# syntax of the XML files.
-
-XML_DTD                =
-
 # If the XML_PROGRAMLISTING tag is set to YES Doxygen will
 # dump the program listings (including syntax highlighting
 # and cross-referencing information) to the XML output. Note that
@@ -1653,15 +1618,6 @@ HAVE_DOT               = YES
 
 DOT_NUM_THREADS        = 0
 
-# By default doxygen will use the Helvetica font for all dot files that
-# doxygen generates. When you want a differently looking font you can specify
-# the font name using DOT_FONTNAME. You need to make sure dot is able to find
-# the font, which can be done by putting it in a standard location or by setting
-# the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the
-# directory containing the font.
-
-DOT_FONTNAME           = FreeSans
-
 # The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs.
 # The default size is 10pt.
 

doc/ns3_html_theme/static/ns3_version.js

@@ -1,7 +1,7 @@
 // ns3_version.js:  automatically generated
 //  public urls
 var ns3_host = "/";
-var ns3_version = "Release <a href=\"http://www.nsnam.org/overview/projects/direct-code-execution/dce-1.9\">dce-1.9</a>";
+var ns3_version = "Release <a href=\"http://www.nsnam.org/overview/projects/direct-code-execution/dce-1.9\">DCE_VERSION</a>";
 var ns3_release = "docs/dce/release/1.9/";
 var ns3_local = "";
 var ns3_doxy  = "doxygen/";

doc/source/conf.py

@@ -11,7 +11,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys, os, subprocess
+import re
 
 # 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
@@ -47,10 +48,9 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# The short X.Y version.
-version = '1.9'
 # The full version, including alpha/beta/rc tags.
-release = '1.9'
+release = re.sub('^dce-', '', os.popen('git describe --tags').read().strip())
+version = release
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -91,11 +91,11 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#html_theme = 'default'
+html_theme = 'default'
 #html_theme = 'agogo'
 #html_theme = 'traditional'
 #html_theme = 'scrolls'
-html_theme = 'sphinxdoc'
+#html_theme = 'sphinxdoc'
 
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -221,3 +221,11 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 
+
+## For doxygen generation at readthedocs.io
+read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+
+if read_the_docs_build:
+    subprocess.call('sed -i "s/doc$/doc\/source\/_build\/html\/doxygen/" ../doxygen.conf', shell=True)
+    subprocess.call('sed -i "s/DCE_VERSION/dce-%s"/ ../doxygen.conf' % release, shell=True)
+    subprocess.call('cd ../../ ; doxygen doc/doxygen.conf', shell=True)

doc/source/getting-started.rst

@@ -44,11 +44,11 @@ then you must to create a directory for DCE and install it using bake:
 
    mkdir dce
    cd dce
-   bake.py configure -e dce-ns3-|version|
+   bake.py configure -e dce-ns3-$version
    bake.py download
    bake.py build
  
-note that dce-ns3-|version| is the DCE version |version| module. If you would like to use the development version of DCE module, you can specify **dce-ns3-dev** as a module name for bake.
+note that dce-ns3-$version is the DCE module with a version number. If you would like to use the development version of DCE module, you can specify **dce-ns3-dev** as a module name for bake.
 
 the output should look likes this:
 
@@ -84,11 +84,11 @@ The difference to build the advanced mode is the different module name *dce-linu
 
     mkdir dce
     cd dce
-    bake.py configure -e dce-linux-|version|
+    bake.py configure -e dce-linux-$version
     bake.py download
     bake.py build
 
-note that dce-linux-|version| is the DCE version |version| module. If you would like to use the development version of DCE module, you can specify **dce-linux-dev** as a module name for bake.
+note that dce-linux-$version is the DCE module with a version number. If you would like to use the development version of DCE module, you can specify **dce-linux-dev** as a module name for bake.
 
 
 Building DCE using WAF

doc/source/index.rst

@@ -5,8 +5,8 @@ Direct Code Execution (DCE) Manual
 
 This is the manual of Direct Code Execution (DCE).
 
-* `Doxygen <http://www.nsnam.org/docs/dce/doxygen/index.html>`_: Documentation of the public APIs of the DCE
-* Manual *(this document)* for the `latest release <http://www.nsnam.org/docs/dce/release/latest/manual/html/index.html>`_ and `development tree <http://www.nsnam.org/docs/dce/manual/html/index.html>`_
+* `Doxygen <./doxygen/html/>`_: Documentation of the public APIs of the DCE
+* Manual *(this document)* for the `latest release <../latest/>`_ and `development tree <../latest/>`_
 
 This document is written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ for `Sphinx <http://sphinx.pocoo.org/>`_ and is maintained in the
 ``doc/`` directory of ns-3-dce's source code.