bullet-db / bullet-db.github.io

This hosts the documentation source and examples for Bullet.

bullet-docs

This hosts the documentation source and examples for Bullet.

The built documentation can be accessed here.

Installing mkdocs

You will need Python 2 installed.

You can install the required tool "mkdocs" like this (a "mkdocs" directory will be created wherever you execute these commands):

sudo pip install virtualenv
virtualenv -p `which python2` mkdocs
source mkdocs/bin/activate
pip install mkdocs==0.16.3
pip install mkdocs-cinder
pip install git+https://github.com/twardoch/clinker-mktheme.git@master --upgrade

The above commands will install mkdocs along with the mkdocs theme : Cinder.

Since Cinder has not been upgraded in a while, it uses the changes in this PR of Cinder found here: twardoch/clinker-mktheme.

JavaDocs are Added When Releasing

Note: If you build and serve the site locally you will not be able to see the JavaDocs, you will only see simple place-holder pages (these are required or mkdocs will complain). The JavaDocs are added during the release process.

Running make release will save the docs currently in the master branch, and then replace the place-holder pages with the docs currently on master.

To add new JavaDocs:

• In src branch:
  • Create new folder for the docs. e.g. mkdir -p docs/apidocs/bullet-core/0.4.3/
  • Create a place-holder file. e.g. cp docs/apidocs/bullet-core/0.4.2/index.html docs/apidocs/bullet-core/0.4.3/
  • Add the appropriate link in docs/releases.md (or wherever you want the link). e.g. [JavaDocs](apidocs/bullet-core/0.4.3/index.html)
  • Commit these changes to the src branch. e.g. git add -A && git commit -m "Added new JavaDocs"
  • Push src branch to remote
• Build a release: make release - this will leave you in the master branch with a new build ready NOT including the new docs you want to add
• In master branch after doing "make release" BEFORE pushing to remote:
  • Create new folder for the docs. e.g.: mkdir -p apidocs/bullet-core/0.4.3
  • Copy the contents of the new JavaDocs into the new folder. e.g. cp -r ~/PATH-TO-NEW-DOCS/bullet-core/target/site/apidocs/* apidocs/bullet-core/0.4.3/
  • Commit these changes and amend the last commit (the regular build without your docs) to the master branch. e.g. git add -A && git commit --amend
  • Push master branch to remote

Building the Documentation

While mkdocs is available:

make build will build the documentation.

make serve will serve the documentation so it can be viewed from a local browser.

make release will build a release and commit it to your local "master" branch. This command assumes you have a clean git environment ("git diff" prints nothing). It will build the documentation and commit it to your local master branch. YOU must push the changes in your master branch to the remote repo if you want to publish the changes after the command completes successfully.

Building the examples

You will need Maven 3 and JDK 8 installed to build the examples.

cd bullet-docs/examples/ && make

Code licensed under the Apache 2 license. See LICENSE file for terms.