diff options
author | Sergey Karayev <sergeykarayev@gmail.com> | 2014-07-11 14:00:56 -0700 |
---|---|---|
committer | Sergey Karayev <sergeykarayev@gmail.com> | 2014-07-11 14:00:56 -0700 |
commit | 54c94190a939ad9719f7cb788d63e92e5849bce5 (patch) | |
tree | 316558ef8e4cc923554a29336d1928832e8dcf1c /docs | |
parent | 0de282ce21e4495dd1d0f514b01dddb3d761e10f (diff) | |
download | caffeonacl-54c94190a939ad9719f7cb788d63e92e5849bce5.tar.gz caffeonacl-54c94190a939ad9719f7cb788d63e92e5849bce5.tar.bz2 caffeonacl-54c94190a939ad9719f7cb788d63e92e5849bce5.zip |
[docs] updated instructions for contributing documentation
Diffstat (limited to 'docs')
-rw-r--r-- | docs/development.md | 11 |
1 files changed, 8 insertions, 3 deletions
diff --git a/docs/development.md b/docs/development.md index 444c9e8e..d3b0e8c3 100644 --- a/docs/development.md +++ b/docs/development.md @@ -9,9 +9,14 @@ The [BVLC](http://bvlc.eecs.berkeley.edu/) maintainers welcome all contributions ### Documentation -Tutorials and general documentation -- including this website -- are written in Markdown format in the `docs/` folder. -While the format is quite easy to read directly, you may prefer to view the whole thing as a website. -To do so, simply run `jekyll serve -s docs` and view the documentation website at `http://0.0.0.0:4000` (for [jekyll](http://jekyllrb.com/), you must have ruby and do `gem install jekyll`). +This website, written with [Jekyll](http://jekyllrb.com/), functions as the documentation portal -- simply run `scripts/build_docs.sh` and view the website at `http://0.0.0.0:4000`. + +We prefer tutorials and examples to be documented close to where they live, in `readme.md` files. +The `build_docs.sh` script gathers all `examples/**/readme.md` and `examples/*.ipynb` files, and makes a table of contents. +To be included in the docs, the readme files must be annotated with [YAML front-matter](http://jekyllrb.com/docs/frontmatter/), including the flag `include_in_docs: true`. +Similarly for IPython notebooks: simply include `"include_in_docs": true` in the `"metadata"` JSON field. + +Other docs, such as installation guides, are written in the `docs` directory and manually linked to from the `index.md` page. We strive to provide provide lots of usage examples, and to document all code in docstrings. We absolutely appreciate any contribution to this effort! |