Contributing to documentation

Note

Tips for contributors who are new to the highly-dynamic environment of documentation in AI software:

  • A good place to start is “document something you figured out how to get working”. Content changes and additions should be targeted at something more specific than “developers”. If you don’t understand how varied and wide the audience is, you’ll inadvertently break or block things.
  • There are experts who work on all parts of the stack; try asking how documentation changes ought to be made in their respective sections.
  • Start with something small. It is okay to add a “patch” to fix a typo or suggest a word change; larger changes to files or structure require research and testing first, as well as some logic for why you think something needs changed.
  • Most documentation should wrap at about 80. We do our best to help authors source-link and maintain their own code and contributions; overwriting something already documented doesn’t always improve it.
  • Be careful editing files with links already present in them; deleting links to papers, citations, or sources is discouraged.
  • Please do not submit Jupyter* notebook code to the nGraph Library or core repos; best practice is to maintain any project-specific examples, tests, or walk-throughs in a separate repository and to link back to the stable op or Ops that you use in your project.

For updates within the 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 changes made, additions, deletions, and feature requests.

If you prefer to use a containerized application, like Jupyter* notebooks, Google Docs*, the GitHub* GUI, 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 efforts 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. Add a note on our wiki to show us what you did; new and novel applications may have their projects highlighted on an upcoming ngraph.ai release.

Note

Please do not submit Jupyter* notebook code to the nGraph Library or core repos; best practice is to maintain any project-specific examples, tests, or walk-throughs in a separate repository.

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 nGraph Library’s 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.27 version of 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, sizeof(v_a));
    t_b->write(&v_b, sizeof(v_b));
    t_c->write(&v_c, 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.

How to 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 Sphinx==1.7.5
$ pip3 install breathe numpy
$ 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, try:

$ python3 -m venv py3doc
$ . py3doc/bin/activate
(py3doc)$ pip install 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.