nGraph Library docs

Read this for changes affecting anything in ngraph/doc

For updates to the Intel® nGraph Library /doc repo, please submit a PR with any changes or ideas you’d like integrated. This helps us maintain trackability with respect to additions or feature requests.

If you prefer to use a containerized application, like Jupyter* notebooks, Google Docs*, or MS Word* to explain, write, or share documentation contributions, you can convert the doc/sphinx/source/*.rst files to another format with a tool like pypandoc and share a link to your docs on our wiki.

Another option is to fork the ngraph repo, essentially snapshotting it at that point in time, and to build a Jupyter* notebook or other set of docs around it for a specific use case; then share a link with the community on our wiki.

Note

Please do not submit Jupyter* notebook code to the Intel nGraph library or core repos; best practice is to maintain any project-specific examples, tests, or walk-throughs separately.

Documenting source code examples

When verbosely documenting functionality of specific sections of code – whether they are entire code blocks within a file, or code strings that are outside the Intel nGraph documentation repo, here is an example of best practice:

Say a file has some interesting functionality that could benefit from more explanation about one or more of the pieces in context. To keep the “in context” navigable, write something like the following in your .rst documentation source file:

.. literalinclude:: ../../../examples/abc/abc.cpp
   :language: cpp
   :lines: 20-31

And the raw code will render as follows

using namespace ngraph;

int main()
{
    // Build the graph
    Shape s{2, 3};
    auto a = std::make_shared<op::Parameter>(element::f32, s);
    auto b = std::make_shared<op::Parameter>(element::f32, s);
    auto c = std::make_shared<op::Parameter>(element::f32, s);

    auto t0 = std::make_shared<op::Add>(a, b);

You can now verbosely explain the code block without worrying about breaking the code. The trick here is to add the file you want to reference relative to the folder where the Makefile is that generates the documentation you’re writing.

See the note at the bottom of this page for more detail about how this works in the current 0.14 version of Intel nGraph library documentation.

Adding captions to code blocks

One more trick to helping users understand exactly what you mean with a section of code is to add a caption with content that describes your parsing logic. To build on the previous example, let’s take a bigger chunk of code, add some line numbers, and add a caption:

.. literalinclude:: ../../../examples/abc/abc.cpp
   :language: cpp
   :lines: 48-56
   :caption: "caption for a block of code that initializes tensors"

and the generated output will show readers of your helpful documentation

“caption for a block of code that initializes tensors”
    // Initialize tensors
    float v_a[2][3] = {{1, 2, 3}, {4, 5, 6}};
    float v_b[2][3] = {{7, 8, 9}, {10, 11, 12}};
    float v_c[2][3] = {{1, 0, -1}, {-1, 1, 2}};

    t_a->write(&v_a, 0, sizeof(v_a));
    t_b->write(&v_b, 0, sizeof(v_b));
    t_c->write(&v_c, 0, sizeof(v_c));

Our documentation practices are designed around “write once, reuse” that we can use to prevent code bloat. See the Contribution Guide for our code style guide.

Build the documentation

Note

Stuck on how to generate the html? Run these commands; they assume you start at a command line running within a clone (or a cloned fork) of the ngraph repo. You do not need to run a virtual environment to create documentation if you don’t want; running $ make clean in the doc/sphinx folder removes any generated files.

Right now the minimal version of Sphinx needed to build the documentation is Sphinx v. 1.7.5. This can be installed with pip3, either to a virtual environment, or to your base system if you plan to contribute much core code or documentation. For C++ API docs that contain inheritance diagrams and collaboration diagrams which are helpful for framework integratons, building bridge code, or creating a backend UI for your own custom framework, be sure you have a system capable of running doxygen.

To build documentation locally, run:

$ sudo apt-get install python3-sphinx
$ pip3 install [-I] Sphinx==1.7.5 [--user]
$ pip3 install [-I] breathe numpy [--user]
$ cd doc/sphinx/
$ make html
$ cd build/html
$ python3 -m http.server 8000

Then point your browser at localhost:8000.

To build documentation in a python3 virtualenv, run:

$ python3 -m venv py3doc
$ . py3doc/bin/activate
(py3doc)$ pip install python3-sphinx breathe numpy
(py3doc)$ cd doc/sphinx
(py3doc)$ make html
(py3doc)$ cd build/html
(py3doc)$ python -m http.server 8000

Then point your browser at localhost:8000.

Note

For docs built in a virtual env, Sphinx latest changes may break documentation; try building with a specific version of Sphinx.

For tips on writing reStructuredText-formatted documentation, see the sphinx stable reST documentation.