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     ! 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``.