1esnet-gh-pages-base 2=================== 3 4Base templates for ESnet's GitHub pages. These pages are created using the 5Sphinx_ documentation package using the sphinx-bootstrap-theme_ with some 6pages. This repo is meant to be included into a project using git subtree and 7provides 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 12Installation 13------------ 14 151. 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. 172. ``cd $PROJECT_ROOT`` 183. ``mkdir docs`` 194. ``git subtree add --prefix docs/_esnet https://github.com/esnet/esnet-gh-pages-base.git master --squash`` 205. ``cd docs`` 216. ``sphinx-quickstart`` 227. ``ln -s ../_esnet/static _static/esnet`` 238. edit ``conf.py`` as described in the next section 24 25Editing conf.py 26^^^^^^^^^^^^^^^ 27 28``sphinx-quickstart`` creates a basic conf.py file, however to use the ESnet 29theme 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 65That's it! 66 67Sphinx Installation using Mac OS X Base Python 68^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 69 701. sudo /usr/bin/easy_install pip 712. sudo /usr/local/bin/pip install sphinx sphinx-bootstrap-theme 72 73Sphinx Installation using MacPorts 74^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 75 761. port install python27 py27-pip py27-sphinx 772. port select pip py27-pip 783. port select sphinx py27-sphinx 794. pip install sphinx sphinx-bootstrap-theme # make sure this is 80 /opt/local/bin/pip 81 82Creating Content, Previewing and Publishing 83------------------------------------------- 84 85The 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 87documentation for Sphinx_. 88 89Building HTML 90^^^^^^^^^^^^^ 91 92In the ``docs`` directory run ``make clean html``. 93 94Previewing the site 95^^^^^^^^^^^^^^^^^^^ 96 97``open _build/html/index.html`` 98 99or 100 101``open -a /Application/Google\ Chrome.app _build/html/index.html`` 102 103Publishing the site 104^^^^^^^^^^^^^^^^^^^ 105 106From the ``docs`` directory run ``_esnet/deploy.sh``. It will be visible at: 107``http://github.com/esnet/PROJECT``. 108
