Return to README.rst CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iperf / docs / _esnet

iperf3 3.1.3

    1: esnet-gh-pages-base
    2: ===================
    3: 
    4: Base templates for ESnet's GitHub pages. These pages are created using the
    5: Sphinx_ documentation package using the sphinx-bootstrap-theme_ with some
    6: pages.  This repo is meant to be included into a project using git subtree and
    7: provides the overrides and customizations to the base theme.
    8: 
    9: .. _Sphinx: http://sphinx-doc.org
   10: .. _sphinx-bootstrap-theme: https://github.com/ryan-roemer/sphinx-bootstrap-theme
   11: 
   12: Installation
   13: ------------
   14: 
   15: 1. Install Sphinx and sphinx-bootstrap-theme. See the instructions below for
   16:    installing these either using the Mac OS X base system python or MacPorts.
   17: 2. ``cd $PROJECT_ROOT``
   18: 3. ``mkdir docs``
   19: 4. ``git subtree add --prefix docs/_esnet https://github.com/esnet/esnet-gh-pages-base.git master --squash``
   20: 5. ``cd docs``
   21: 6. ``sphinx-quickstart``
   22: 7. ``ln -s ../_esnet/static _static/esnet``
   23: 8. edit ``conf.py`` as described in the next section
   24:   
   25: Editing conf.py
   26: ^^^^^^^^^^^^^^^
   27: 
   28: ``sphinx-quickstart`` creates a basic conf.py file, however to use the ESnet
   29: theme we need to make some changes. Make the following changes to conf.py::
   30: 
   31:    # add this with the imports at the top of the file
   32:    import sphinx_bootstrap_theme
   33: 
   34:    # change templates_path to this
   35:    templates_path = ['_esnet/templates']
   36: 
   37:    # add _esnet to exclude_patterns
   38:    exclude_patterns = ['_build', '_esnet']
   39: 
   40:    # change html_theme and html_theme_path:
   41:    html_theme = 'bootstrap'
   42:    html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
   43: 
   44:    # add html_theme options:
   45:    html_theme_options = {
   46:           "navbar_pagenav": False,
   47:           "nosidebar": False,
   48:           "navbar_class": "navbar",
   49:           "navbar_site_name": "Section",
   50:           "source_link_position": "footer",
   51:        "navbar_links": [
   52:            ("Index", "genindex"),
   53:            ("ESnet", "https://www.es.net", True),
   54:        ],
   55:    }
   56: 
   57:    # add html_logo and html_sidebars
   58:    html_logo = "_esnet/static/logo-esnet-ball-sm.png"
   59:    html_sidebars = {'index': None, 'search': None, '*': ['localtoc.html']}
   60:    html_favicon = "_esnet/static/favicon.ico"
   61:    html_context = {
   62:       "github_url": "https://github.com/esnet/PROJNAME",
   63:    }
   64: 
   65: That's it!
   66: 
   67: Sphinx Installation using Mac OS X Base Python
   68: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   69: 
   70: 1. sudo /usr/bin/easy_install pip
   71: 2. sudo /usr/local/bin/pip install sphinx sphinx-bootstrap-theme
   72: 
   73: Sphinx Installation using MacPorts
   74: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   75: 
   76: 1. port install python27 py27-pip py27-sphinx
   77: 2. port select pip py27-pip
   78: 3. port select sphinx py27-sphinx
   79: 4. pip install sphinx sphinx-bootstrap-theme # make sure this is
   80:    /opt/local/bin/pip
   81: 
   82: Creating Content, Previewing and Publishing
   83: -------------------------------------------
   84: 
   85: The files are in the ``docs`` directory.  Take a look at the content of
   86: ``index.rst``.  Take a look at the docs from other projects and review the
   87: documentation for Sphinx_.
   88: 
   89: Building HTML
   90: ^^^^^^^^^^^^^
   91: 
   92: In the ``docs`` directory run ``make clean html``.
   93: 
   94: Previewing the site
   95: ^^^^^^^^^^^^^^^^^^^
   96: 
   97: ``open _build/html/index.html``
   98: 
   99: or
  100: 
  101: ``open -a /Application/Google\ Chrome.app _build/html/index.html``
  102: 
  103: Publishing the site
  104: ^^^^^^^^^^^^^^^^^^^
  105: 
  106: From the ``docs`` directory run ``_esnet/deploy.sh``.  It will be visible at:
  107: ``http://github.com/esnet/PROJECT``.