This repository contains the source files for Intel Aero documentation. In order to use it you need to have mkdocs and its themes/extensions installed.
There's a Makefile in this repository that's mostly a wrapper around mkdocs with some extra functionality related to this site.
In order to build the documentation we need only python from the host system. Additional dependencies are installed via pip. The preferred method is to install them with:
make setup
This will install all required packages with pip install --user --upgrade
git clone [email protected]:intel-aero/intel-aero-docs.git
cd intel-aero-docs
Edit (or include) .md files using the same syntax used by Github wiki (markdown). There this helpful guide that describes the syntax, with examples.
To change the documentation and visualize what's being changed, start mkdocs's webserver:
# this is just a wrapper to "mkdocs serve"
make serve
When it's done, proceed to commit the changes using the regular git flow:
# Check changes not commited
git status
# Add modified files to the next commit
git add modified_file.md
# Commit
git commit -m "modified_file: Summary of modifications"
# Push to a branch for review
git push origin myusername-identifier
Then proceed with the regular pull request flow in the Github web interface. This will notify members of the intel-aero organization so the modification can be reviewed and later merged.
Set DEST variable and call make deploy
or make publish
:
export DEST=remote-server:/var/www/intel-aero-docs
make deploy
Rsync needs to be installed to synchronize the site built locally with
the remote one. If DEST isn't set, it will install to /tmp/intel-aero-docs