Contributing

Thank you for your interest in this project! Please refer to the following sections on how to contribute code and bug reports.

Reporting bugs

At the moment, this project is run in the spare time of a single person (Wenzel Jakob) with very limited resources for issue tracker tickets. Thus, before submitting a question or bug report, please take a moment of your time and ensure that your issue isn’t already discussed in the project documentation elsewhere on this site.

Feature requests are generally closed unless they come with a pull request that implements the desired functionality.

Assuming that you have identified a previously unknown problem or an important question, it’s essential that you submit a self-contained and minimal piece of code that reproduces the problem. In other words: no external dependencies, isolate the function(s) that cause breakage, submit matched and complete C++ or Python snippets (depending on how you are using NanoGUI) that can be easily compiled and run on my end.

Pull requests

Contributions are submitted, reviewed, and accepted using Github pull requests. Please refer to this article for details and adhere to the following rules to make the process as smooth as possible:

• Make a new branch for every feature you’re working on.
• Make small and clean pull requests that are easy to review but make sure they do add value by themselves.
• Make sure you have tested any new functionality (e.g. if you made a new Widget).
• This project has a strong focus on providing general solutions using a minimal amount of code, thus small pull requests are greatly preferred.
• Read the remainder of this document, adhering to the bindings and documentation requirements.
• If making a purely documentation PR, please prefix the commit with [docs]
  • E.g. [docs] Adding documentation for class X.

Python Binding Requirements

Since NanoGUI builds for both C++, as well as produces Python bindings, you must account for both sides of the API regardless of how you use the project. If you are adding a new method, class, etc (not fixing an existing one), you must write the code to produce the relevant binding in python/python.cpp.

Code Style Requirements

• Tabs are 4 spaces – please do not submit PRs with tab characters.

• Most code follows an 80 column ruler, wherever reasonable.

• Pointers and references have modifiers next to variable name, not the type:

  • Yes: void *p, No: void* p
  • Yes: Color &c, No: Color& c

• Template classes / functions: template <typename T> method()

  • Space between template and <, on same line where reasonable

• Opening curly braces for definitions / loops / ifs are on the same line as the statement

  • Yes:

    for (auto &&c : myVec) {
        // ... computation ...
    }
    

  • No:

    for(auto &&c : myVec)
    {
        // ... computation ...
    }
    

Code Documentation Requirements

When adding new classes, methods, etc please provide meaningful and well formatted documentation of the new functionality. We use Doxygen comments to document the code, using the “JavaDoc” style. For consistency, please do not use the QT or other formats.

If you are familiar with how to use Doxygen-style comments:

• You should indent by four spaces for things like param, etc.
• \brief: a brief description.
• \tparam: a template parameter.
• \param: a parameter.
• \return: what the return value represents (where applicable).

For a quick crash-course on documenting using Doxygen:

1. If you are adding a new file, please include the disclaimer at the top immediately followed by /** \file */. So if you are creating the file nanogui/file.h

   /*
    nanogui/file.h -- A brief description of what the file contains.
   
    NanoGUI was developed by Wenzel Jakob <wenzel.jakob@epfl.ch>.
    The widget drawing code is based on the NanoVG demo application
    by Mikko Mononen.
   
    All rights reserved. Use of this source code is governed by a
    BSD-style license that can be found in the LICENSE.txt file.
   */
   /** \file */
   

   changing the first line to the right name / description of your file.

2. Documenting a newly added Struct or Class requires special attention. If you are adding a class Thing in file nanogui/thing.h, the class level documentation needs to explicitly declare the location for Doxygen to parse everything correctly.

   /**
    * \class Thing thing.h nanogui/thing.h
    *
    * This is the actual documentation for the thing.
    */
   class Thing { ... };
   

   This simply tells Doxygen how to format the various include directives. If you are writing a Struct, replace \class with \struct.

3. Please fully document all parameters, template parameters, and return types where applicable. In some cases it is sufficient to include just a brief one-line documentation string, e.g. the for the nanogui::Screen::caption() method, it is simple enough that the following is sufficient (note the three ///):

   /// Get the window title bar caption
   const std::string &caption() const { return mCaption; }
   

   However, more complicated methods should be thoroughly documented. As an example, this method demonstrates template parameters, parameters, and return value documentation:

   /**
    * \brief A useless function for getting sizes.
    *
    * This method has specific things that must be pointed out, but they
    * were too long to include in the 'brief' documentation.
    *
    * \tparam T
    *     The type we are evaluating the size of.
    *
    * \param returnFake
    *     If set to true, a random positive number will be returned. This
    *     comment is a bit longer and can span multiple lines, making sure
    *     to indent each new line.
    *
    *     Warning: this had an empty line before it and will NOT appear in
    *     the documentation of this parameter, but instead it will appear
    *     in the documentation of the method!
    *
    * \return
    *     The result of ``sizeof(T)``.
    */
   template <typename T>
   size_t exampleTemplateFunction(bool returnFake = false) { ... }
   

Styling the Code

Since we are using both Doxygen and Sphinx, we have access to a wealth of interesting documentation styling.

From Doxygen:

You can use things like \throws, \remark, and even \ref to generate html links to other items.

From Sphinx:

On the Sphinx side, you now have access to full reStructuredText syntax. This includes:

• **bold** to make bold text
• *italics* for italics
• ``teletype`` for teletype text.

You can additionally include more complex reStructuredText such as grid tables, as well as Sphinx directives. You will need to use the \rst and \endrst commands for these:

/**
 * \brief Some method you are documenting.
 *
 * \rst
 * I am now in a verbatim reStructuredText environment, and can create a grid table.
 *
 * I could create a python code listing using
 *
 * .. code-block:: py
 *
 *    print("Some python code.")
 *
 * You can also use the note or warning directives to highlight important concepts:
 *
 * .. note::
 *    You may or may not segfault.
 *
 * .. warning::
 *    I guarantee you will segfault.
 * \endrst
 */

Warning

In normal reStructuredText, if you simply indent a block of code by four spaces it will render as a code listing. While this will build as expected for the C++ documentation on RTD, it will fail to build py_doc.h correctly.

For code listings, always begin an \rst section and use .. code-block as shown above.

TODO

Documentation Completion

Already familiar with NanoGUI or a subset of its classes? The documentation for the following files is incomplete, waiting for your PR. Document a whole class, or even just a method of a given class.

If you make progress on / complete an item with your PR, please update / remove it from the table on this page (docs/contributing.rst).

Note

The NanoGUI documentation hosted online does not include private methods or member variables at this time. However, documentation for these is welcome!

Warning

In some of these files, you will see preprocessor blocks like

#ifndef DOXYGEN_SHOULD_SKIP_THIS
... code that the breaks the documentation ...
#endif // DOXYGEN_SHOULD_SKIP_THIS

Please take care not to remove these!

Filename	Action Item
button.h	Most member methods. All member variables.
checkbox.h	All member methods and variables.
colorpicker.h	Constructor and callback. All member variables.
colorwheel.h	Most methods and member variables.
combobox.h	Most member methods and variables.
formhelper.h	More detailed documentation explaining parameters for FormHelper methods. Most member variables.
graph.h	All member methods and variables.
imagepanel.h	All member methods and variables.
imageview.h	Most member methods.
label.h	Some member methods and variables.
layout.h	Nearly everything.
popup.h	Some member methods and variables. Explicit parameter documentation would be very useful.
popupbutton.h	Almost everything.
progressbar.h	Almost everything.
screen.h	Documentation for the manual GLFW API. All member variables.
slider.h	Almost everything.
stackedwidget.h	Almost everything.
tabheader.h	Some member methods. Some reformatting of existing documentation to use \param or \return etc.
tabwidget.h	Some member methods. Some reformatting of existing documentation to use \param or \return etc.
textbox.h	Almost everything.
theme.h	Explicit documentation for what these all represent.
toolbutton.h	Documentation of the constructor explaining the range of values that can be used for icon. Or at least where to look for that?
vscrollpanel.h	Almost everything.
widget.h	Member variables.
window.h	Some member methods. All member variables.

Advanced Contribution Opportunity

Currently, all partial and full template specializations are skipped. Specifically, nearly everything in include/nanogui/serializer/*. According to the Breathe documentation this should be possible. The likely cause of this issue is that the version of Breathe packaged for use with pip is not up to date. Your task would be to find a way to use docs/requirements.txt to install the current source from the master branch of Breathe instead of using PyPi.

You can test locally by making sure you do not have Breathe installed with pip, and compiling it yourself (make sure you add it to your PATH so you can use it in Python).

Then try moving the #ifndef DOXYGEN_SHOULD_SKIP_THIS to expose a single template specialization in a file of your choice, and try and get the documentation to build. If you succeed with this, the next step will be to find a way to get Read the Docs to build the current source of Breathe rather than using PyPi.

In theory, all of these are possible.