Shogun comes with automatically generated API examples in all interface languages, see our website. This readme describes their mechanics and how they are used for documentation. See also DEVELOPING.md for their role in testing.
In Shogun, writing a single example files covers all interface languages at once, a subset can be seen on our website.
The listings that can be found in
examples/meta/src/*/*.sg contain example code in a meta-language that is specific to Shogun. During the build, these are parsed and then translated with the (Python) machinery in
examples/meta/generator/*.py. The output is a code listing for each target language defined in
examples/meta/src/generator/targets/*.json. The process can be invoked with
This is only available when the cmake option
BUILD_META_EXAMPLES=ON is set, and the Python requirements in
examples/meta/requirements.txt are met.
The C++ examples are always available, you can compile them using
make or more specifically
and run them as from their folder straight-away (you might have to set environmental variables, see INTERFACES.md)
cd examples/meta/cpp/multiclass_classifier ./knn ./svm
For details, see
examples/meta/ for details,
Adding new examples
It is extremely simple to add a new example: simple create another
*.sg file. We are currently porting all existing Python examples in the deprecated folder
examples/undocumented/python_modular to the new system -- a copy paste entrance task.
If you porting an example is great, even better is when it comes with integration testing data of the numerical output, as described in DEVELOPING.md.
Please take inspiration from the existing examples, especially those that were written as part of the Google Summer of Code 2016.
Please don't break the build. Always compile and run at least the C++ version of the example.
Check potential requirements of C++ guards that can make a class used in the example unavailable (
USE_GPL_SHOGUN, etc); potentially add them here.
The The Shogun API cookbook is a web-based version that adds additional documentation to an existing example. The idea is that code snippets (rather than the full listing) from the automatically generated listings can be embedded in a markdown page that describes details, math, and references for the example. The pages are rendered with our own plugin for Sphinx.
Adding a page
To add an entry for an existing example, create a markdown
*.rst file with matching filename and directory. E.g. for the example
examples/meta/src/multiclass_classifier/knn.sg, this would be
Edit the file so that it contains details on API example and references to code snippets. The point is to not show the full file listing but only snippets. The file should furthermore contain basic math in the form of LaTeX, important references (wikipedia, scientific paper references using BibTeX, other pages, etc). Take inspiration from existing pages.
If you are adding a new topic (like "kernels" or "regression") you will also need to update the
index.rst file in
doc/cookbook/source/. Follow the template of the existing cookbooks.
Tips for cookbook pages
- Orient yourself closely to reference examples, especially those written during the Google Summer of Code 2016.
- Write proper English. Pay attention to grammar, spelling, and punctuation.
- Keep the example specific. Only talk about the particular algorithm and its interface, avoid general concepts (such as 'supervised learning').
- Keep the example local. Only show code snippets that illustrate API usage, avoid showing the full listing.
- Let the code speak for itself. Avoid useless statements that are clear from the code. Avoid statements like "we call the
trainmethod", but rather "we train the model via". This way the
.rstfile is also invariant to API changes.
- All external weblinks are automatically checked and warnings are given if corrupt, but please ensure you do not put in dead links.
- If you want to add a BibTeX reference, add it to references.bib. Please do only use properly formated entries, follow the existing formatting.
- If you need a custom LaTeX operator, simply add it to mathconf.js
Furthermore, if you send a PR, our buildbot will automatically upload a preview of the cookbooks to a temporary location. This is to make our life easier when reviewing the PR.
To make our life even more easy, you should look at the cookbook before sending a PR. You can render it with
which is also part of
make doc. The target might not be available if the requirements in
doc/cookbook/requirements.txt are not satisfied (in particular Sphinx), or if the meta examples are disabled.
After the cookbook has been rendered, you can view it for example running
python -m SimpleHTTPServer
build/doc/cookbook/html directory, and then open your browser at