kwpilot Documentation

Documentation and tutorials for OPRECOMP kwpilot demonstrator.

There are two ways to contribute to the documentation of cloudFPGA project, the automating compilation and and the manual compilation.

Automated documentation compilation

We adopt the following tools for automating the documentation of cloudFPGA project:

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.
Read the Docs (sphinx_rtd_theme) is a sphinx theme designed to look modern and be mobile-friendly.
Travis CI is a hosted continuous integration service used to build and test software projects hosted at GitHub.

The overall documentation compilation process is triggered by a new commit to kwpilot-doc repository. Then Travis CI is building the documentation for the kwpilot (general information, tutorials, etc.)on a containerized environment and pushes the generated static HTML files on the gh_pages branch of kwpilot-doc repository. The repository is configured to match this branch to GitHub Pages and also bypass jekyll processing of GitHub Pages by creating an empty file named .nojekyll on the repository. Eventually the final documentation is available here.

Step 1/1: Update Documentation

git clone git@git@github.com:oprecomp/kwpilot-doc.git kwpilot-doc
cd kwpilot-doc
< ... make your changes ... >
git push
firefox https://oprecomp.github.io/kwpilot-doc/index.html & (view your changes)

NOTE: the documentation compilation on Travis CI is expected to take several minutes, so be patient when you submit changes until the time these take effect on the documentation.

Manual documentation compilation

In case you need to manually compile the documentation of kwpilot project on your local development environment, please follow these steps:

Step 1/3: Sphinx and dependencies setup

To generate the Sphinx based python documentations, you have to setup:

which python3.6
virtualenv sphinx -p /usr/bin/python3.6
. sphinx/bin/activate
git clone git@github.com:oprecomp/kwpilot-doc.git kwpilot-doc
pip install -r ./kwpilot-doc/docsrc/requirements.txt

Step 2/3: Rebuild Documentation

. sphinx/bin/activate
git checkout gh-pages  (assuming you are on kwpilot-doc folder)
< ... make your changes ... >
make clean
make html
firefox _build/html/index.html & (view your changes locally)

Step 3/3: Update Documentation

git checkout gh-pages (ensure you are on this branch)
git commit -am "rebuild docs"
git push