angela-li / handbook

Community Documentation for the Carpentries

About this site

This site is built using the Sphinx documentation generator (a Python tool) and the Read the Docs theme for the style. (Not to be confused with readthedocs.io - the site is not hosted at readthedocs.io!)

For more information about using Sphinx, see the Getting Started guide (sphinx-doc.org) or the Quick Start (readthedocs.io) for an explanation of how to use Sphinx.

Required dependencies

To install the required dependencies (Sphinx and the ReadTheDocs Sphinx theme), execute the following command from the repository directory to install all Python dependencies:

pip install -r requirements.txt 

After installing the dependencies, you can build the site locally by executing the following command from the repository:

$ make html

Open the file _build/html/index.html to preview the site locally. Python offers a quick way to run a web server to serve local files. Run the following:

$ cd _build/html

# Python 2:
$ python2 -m SimpleHTTPServer

# Python 3:
$ python3 -m http.server

In both cases, a local web server will be run on port 8000, so navigate to http://localhost:8000 in your browser to view the site locally.

You can make changes to the contents of the repository, and re-run make html, to update the website contents. If you are having problems with the site not refreshing, you can delete the contents of the _build directory (which are automatically generated) with rm -fr _build/*.

If new files or folders are added to the Handbook, index.rst will need to be updated for those to be included in the final site by Sphinx.

Site structure

The root level index.rst generates the main categories the sidebar navigation. Each sub-section is a folder in the topic_folders directory. Each folder within the topic_folders directory has its own index.rst file. These then expand into the subcategories in each directory.

Within each folder's index.rst file, the section heading is defined by a string of = beneath it. Subheadings can be defined using ### in each markdown file or by a heading with - under it in the index.rst file.

Additional information

This site is built from the master branch of this repo (carpentries/handbook). Changes can be previewed live here: http://docs-src.carpentries.org/. Changes to the actual site https://docs.carpentries.org/ will take several hours to go live once changes have been pushed to Github, since the contents of the site are behind a CDN (Content Distribution Network) that caches content.

If you are making experimental changes to content please be sure to do so in a non-master, non-live branch. When your changes are complete and ready to be pushed to the live site, open a pull request in carpentries/handbook.

Draft content can be added to the drafts folder of the carpentries/userguides repo (in the master branch) without breaking anything. Draft content is not built to the live site and these files may contain inaccurate or out of date information.