Staging

Note

This document will show you how to create a Staging environment to work with Sphinx & Read the Docs.

  1. Assuming you have Python already, install Sphinx Otherwise, please follow steps to install Python. Then do:

1sudo pip install sphinx sphinx-autobuild

  1. Create a directory inside your project to hold your docs:

1cd /path/to/project
2mkdir docs

  1. Run sphinx-quickstart in there:

1cd docs
2sphinx-quickstart

  1. This quick start will walk you through creating the basic configuration; in most cases, you can just accept the defaults. When it’s done, you’ll have an index.rst, a conf.py and some other files. Add these to revision control. Now, edit your index.rst and add some information about your project. Include as much detail as you like. Build them to see how they look:

1make html

Note

You can use sphinx-autobuild to auto-reload your docs. Run sphinx-autobuild . _build/html instead.

  1. To publish only relevant files but NOT the build, _static & _templates directories - please add a .gitignore in the root directory. A sample is below

 1#Folders to ignore
 2build
 3_templates
 4_static
 5
 6#Extensions to ignore
 7*.pyc
 8*.diff
 9*.err
10*.orig
11*.rej
12*.swo
13*.swp
14*.vi
15*.cache
16*.egg-info
17*~
18*#
19
20#Logs and database files to be ignored
21*.log
22*.sql
23*.sqlite
24
25#OS or Editor folders
26.DS_Store
27Thumbs.db
28.cache
29.project
30.settings
31.tmproj
32*.esproj
33nbproject
34*.sublime-project
35*.sublime-workspace
36.tm_properties
37._*

  1. Edit your files to rebuild until you like what you see, then commit your changes and push to your public repository. Once you have Sphinx documentation in a public repository, you can start using Read the Docs.