{"id":19756642,"url":"https://github.com/esnet/esnet-gh-pages-base","last_synced_at":"2025-07-20T00:33:05.477Z","repository":{"id":15354508,"uuid":"18085346","full_name":"esnet/esnet-gh-pages-base","owner":"esnet","description":"ESnet Sphinx documentation theme","archived":false,"fork":false,"pushed_at":"2014-05-05T17:50:54.000Z","size":372,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-02-28T09:11:53.836Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esnet.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-03-25T01:44:13.000Z","updated_at":"2014-05-05T17:51:43.000Z","dependencies_parsed_at":"2022-08-25T08:02:19.044Z","dependency_job_id":null,"html_url":"https://github.com/esnet/esnet-gh-pages-base","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/esnet/esnet-gh-pages-base","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fesnet-gh-pages-base","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fesnet-gh-pages-base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fesnet-gh-pages-base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fesnet-gh-pages-base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esnet","download_url":"https://codeload.github.com/esnet/esnet-gh-pages-base/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esnet%2Fesnet-gh-pages-base/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266048628,"owners_count":23868743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T03:16:31.959Z","updated_at":"2025-07-20T00:33:05.145Z","avatar_url":"https://github.com/esnet.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"esnet-gh-pages-base\n===================\n\nBase templates for ESnet's GitHub pages. These pages are created using the\nSphinx_ documentation package using the sphinx-bootstrap-theme_ with some\npages.  This repo is meant to be included into a project using git subtree and\nprovides the overrides and customizations to the base theme.\n\n.. _Sphinx: http://sphinx-doc.org\n.. _sphinx-bootstrap-theme: https://github.com/ryan-roemer/sphinx-bootstrap-theme\n\nInstallation\n------------\n\n1. Install Sphinx and sphinx-bootstrap-theme. See the instructions below for\n   installing these either using the Mac OS X base system python or MacPorts.\n2. ``cd $PROJECT_ROOT``\n3. ``mkdir docs``\n4. ``git subtree add --prefix docs/_esnet https://github.com/esnet/esnet-gh-pages-base.git master --squash``\n5. ``cd docs``\n6. ``sphinx-quickstart``\n7. ``ln -s ../_esnet/static _static/esnet``\n8. edit ``conf.py`` as described in the next section\n  \nEditing conf.py\n^^^^^^^^^^^^^^^\n\n``sphinx-quickstart`` creates a basic conf.py file. In general the\ndefaults are OK and things can be fixed later by editing conf.py. \nFor author I suggest putting either the names of the people most \ninvolved in writing the docs, the names of the developrs or if all\nelse fails, ESnet is fine. The project release and version should \nmap to the current version of the project your are documenting and it \nis a good idea to try to keep that up to date going forward. It might \nbe worth automating this if you have a way to do so in the project\nworkflow.\n\nHowever to use the ESnet theme we need to make some changes.\nMake the following changes to conf.py::\n\n   # add this with the imports at the top of the file\n   import sphinx_bootstrap_theme\n\n   # change templates_path to this\n   templates_path = ['_esnet/templates']\n\n   # add _esnet to exclude_patterns\n   exclude_patterns = ['_build', '_esnet']\n\n   # change html_theme and html_theme_path:\n   html_theme = 'bootstrap'\n   html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()\n\n   # add html_theme options:\n   html_theme_options = {\n          \"navbar_pagenav\": False,\n          \"nosidebar\": False,\n          \"navbar_class\": \"navbar\",\n          \"navbar_site_name\": \"Section\",\n          \"source_link_position\": \"footer\",\n       \"navbar_links\": [\n           (\"Index\", \"genindex\"),\n           (\"ESnet\", \"https://www.es.net\", True),\n       ],\n   }\n\n   # add html_logo and html_sidebars\n   html_logo = \"_esnet/static/logo-esnet-ball-sm.png\"\n   html_sidebars = {'index': None, 'search': None, '*': ['localtoc.html']}\n   html_favicon = \"_esnet/static/favicon.ico\"\n   html_context = {\n      \"github_url\": \"https://github.com/esnet/PROJNAME\",\n   }\n\nThat's it!\n\nFiles to track in the project repo\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe ``sphinx-quickstart`` command will create a number of files and the \nsphinx build process will make files as well. I suggest not saving \nsphinx build products in the project repo.  This works out to tracking \nthe following files in ``docs``::\n\n   *.rst\n   Makefile\n   conf.py\n   _static/esnet  # to track the symlink created above\n\nYou'll need to ``git add`` these files to your repo.  You may also want to\nadd the following rules to ``${PROJECT_ROOT}/.gitignore``::\n\n   # ignore Sphinx build products\n   /docs/_build\n\nSphinx Installation using Mac OS X Base Python\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n1. sudo /usr/bin/easy_install pip\n2. sudo /usr/local/bin/pip install sphinx sphinx-bootstrap-theme\n\nSphinx Installation using MacPorts\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n1. sudo port install python27 py27-pip py27-sphinx\n2. sudo port select pip py27-pip\n3. sudo port select sphinx py27-sphinx\n4. pip install sphinx sphinx-bootstrap-theme # make sure this is /opt/local/bin/pip\n\nCreating Content, Previewing and Publishing\n-------------------------------------------\n\nThe files are in the ``docs`` directory.  Take a look at the content of\n``index.rst``.  Take a look at the docs from other projects and review the\ndocumentation for Sphinx_.\n\nCreate the ``gh-pages`` branch\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nFollow the instructions at `GitHub gh-pages creation`_ to create the initial\ngh-pages branch.\n\n_`GitHub gh-pages creation`: https://help.github.com/articles/creating-project-pages-manually\n\nBuilding HTML\n^^^^^^^^^^^^^\n\nIn the ``docs`` directory run ``make clean html``.\n\nPreviewing the site\n^^^^^^^^^^^^^^^^^^^\n\n``open _build/html/index.html``\n\nor\n\n``open -a /Application/Google\\ Chrome.app _build/html/index.html``\n\nPublishing the site\n^^^^^^^^^^^^^^^^^^^\n\nFrom the ``docs`` directory run ``_esnet/deploy.sh``.  It will be visible at:\n``http://github.com/esnet/PROJECT``.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesnet%2Fesnet-gh-pages-base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesnet%2Fesnet-gh-pages-base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesnet%2Fesnet-gh-pages-base/lists"}