lancaster-university / microbit-docs

http://lancaster-university.github.io/microbit-docs
Other
27 stars 28 forks source link

microbit-docs

Editing the docs

To edit micro:bit documentation, please edit the raw markdown files contained in the ./docs folder. Please note that any text placed inside a block like this:

[comment]: <> ({"className":"MicroBitAccelerometer"}) 

[comment]: <> ({"end":"MicroBitAccelerometer"})

Will be deleted and regenerated when python doc-gen.py is executed.

We use mkdocs version 0.15.3 to build this site, please use this version only.

mkdocs can be obtained via the pip command.

Live editing

It is recommended that docs are edited locally using mkdocs serve before submitting a pull request with changes.

Generating API documentation

Text placed in the following markdown comments:

[comment]: <> ({"className":"MicroBitAccelerometer"}) 

[comment]: <> ({"end":"MicroBitAccelerometer"})

Is automatically generated by the doc-gen.py script. Any changes made here will not be retained. Changes to API documentation should be made at the source: either microbit-dal or microbit.

Only maintainers of this repository are allowed to push updates to the live site.

Building the docs

To build the docs run the python script with the paths to microbit and microbit-dal as parameters.

python2.7 doc-gen.py -m ../lancasteruni/microbit -d ../lancasteruni/microbit-dal

The variable runtime must be manually changed in mkdocs.yml to match the the version of the DAL that is in use.

Archive

Old versions of the site are contained in the archive folder:

./docs/archive

and can be accessed using the specific version tag:

https://lancaster-university.github.io/microbit-docs/archive/v2.0.0-rc3/

Links to the archived versions are manually added to the /help/ page.

Uploading

To upload the docs to github.io run the python script python2.7 doc-gen.py -g

This will upload to the origin's gh-pages branch