Return to README.rst CVS log

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

Annotation of embedaddon/iperf/docs/_esnet/README.rst, revision 1.1.1.1

1.1       misho       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``.