108 lines
3.2 KiB
ReStructuredText
108 lines
3.2 KiB
ReStructuredText
esnet-gh-pages-base
|
|
===================
|
|
|
|
Base templates for ESnet's GitHub pages. These pages are created using the
|
|
Sphinx_ documentation package using the sphinx-bootstrap-theme_ with some
|
|
pages. This repo is meant to be included into a project using git subtree and
|
|
provides the overrides and customizations to the base theme.
|
|
|
|
.. _Sphinx: http://sphinx-doc.org
|
|
.. _sphinx-bootstrap-theme: https://github.com/ryan-roemer/sphinx-bootstrap-theme
|
|
|
|
Installation
|
|
------------
|
|
|
|
1. Install Sphinx and sphinx-bootstrap-theme. See the instructions below for
|
|
installing these either using the Mac OS X base system python or MacPorts.
|
|
2. ``cd $PROJECT_ROOT``
|
|
3. ``mkdir docs``
|
|
4. ``git subtree add --prefix docs/_esnet https://github.com/esnet/esnet-gh-pages-base.git master --squash``
|
|
5. ``cd docs``
|
|
6. ``sphinx-quickstart``
|
|
7. ``ln -s ../_esnet/static _static/esnet``
|
|
8. edit ``conf.py`` as described in the next section
|
|
|
|
Editing conf.py
|
|
^^^^^^^^^^^^^^^
|
|
|
|
``sphinx-quickstart`` creates a basic conf.py file, however to use the ESnet
|
|
theme we need to make some changes. Make the following changes to conf.py::
|
|
|
|
# add this with the imports at the top of the file
|
|
import sphinx_bootstrap_theme
|
|
|
|
# change templates_path to this
|
|
templates_path = ['_esnet/templates']
|
|
|
|
# add _esnet to exclude_patterns
|
|
exclude_patterns = ['_build', '_esnet']
|
|
|
|
# change html_theme and html_theme_path:
|
|
html_theme = 'bootstrap'
|
|
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
|
|
|
|
# add html_theme options:
|
|
html_theme_options = {
|
|
"navbar_pagenav": False,
|
|
"nosidebar": False,
|
|
"navbar_class": "navbar",
|
|
"navbar_site_name": "Section",
|
|
"source_link_position": "footer",
|
|
"navbar_links": [
|
|
("Index", "genindex"),
|
|
("ESnet", "https://www.es.net", True),
|
|
],
|
|
}
|
|
|
|
# add html_logo and html_sidebars
|
|
html_logo = "_esnet/static/logo-esnet-ball-sm.png"
|
|
html_sidebars = {'index': None, 'search': None, '*': ['localtoc.html']}
|
|
html_favicon = "_esnet/static/favicon.ico"
|
|
html_context = {
|
|
"github_url": "https://github.com/esnet/PROJNAME",
|
|
}
|
|
|
|
That's it!
|
|
|
|
Sphinx Installation using Mac OS X Base Python
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
1. sudo /usr/bin/easy_install pip
|
|
2. sudo /usr/local/bin/pip install sphinx sphinx-bootstrap-theme
|
|
|
|
Sphinx Installation using MacPorts
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
1. port install python27 py27-pip py27-sphinx
|
|
2. port select pip py27-pip
|
|
3. port select sphinx py27-sphinx
|
|
4. pip install sphinx sphinx-bootstrap-theme # make sure this is
|
|
/opt/local/bin/pip
|
|
|
|
Creating Content, Previewing and Publishing
|
|
-------------------------------------------
|
|
|
|
The files are in the ``docs`` directory. Take a look at the content of
|
|
``index.rst``. Take a look at the docs from other projects and review the
|
|
documentation for Sphinx_.
|
|
|
|
Building HTML
|
|
^^^^^^^^^^^^^
|
|
|
|
In the ``docs`` directory run ``make clean html``.
|
|
|
|
Previewing the site
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
``open _build/html/index.html``
|
|
|
|
or
|
|
|
|
``open -a /Application/Google\ Chrome.app _build/html/index.html``
|
|
|
|
Publishing the site
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
From the ``docs`` directory run ``_esnet/deploy.sh``. It will be visible at:
|
|
``http://github.com/esnet/PROJECT``.
|