Update license year and fix docs (#385)
* update license year
* [docs] fix misc style updates and broken links
- fix broken internal links on Usage
- generate to _doxygen rather than doxyoutput
- html_theme now sets pygments_style (revert to original)
- contributing:
- fix invalid definition lists (From {Doxygen,Sphinx})
- remove stale TODO
master
Stephen McDowell
Wenzel Jakob
parent
d9c9e6a686
commit
4b6133d2c8
|
|
@ -26,7 +26,7 @@ libnanogui.dylib
|
|||
# html documentation specific
|
||||
*.pyc
|
||||
docs/_build
|
||||
docs/doxyoutput
|
||||
docs/_doxygen
|
||||
docs/api
|
||||
|
||||
# entypo update generation
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
Copyright (c) 2017 Wenzel Jakob <wenzel.jakob@epfl.ch>, All rights reserved.
|
||||
Copyright (c) 2019 Wenzel Jakob <wenzel.jakob@epfl.ch>, All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions are met:
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ help:
|
|||
.PHONY: help Makefile clean
|
||||
|
||||
clean:
|
||||
rm -rf doxyoutput/ api/
|
||||
rm -rf _doxygen/ api/
|
||||
@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ extensions = [
|
|||
]
|
||||
|
||||
# Setup the `breathe` extension
|
||||
breathe_projects = { "NanoGUI": "./doxyoutput/xml" }
|
||||
breathe_projects = { "NanoGUI": "./_doxygen/xml" }
|
||||
breathe_default_project = "NanoGUI"
|
||||
|
||||
# Setup the `exhale` extension
|
||||
|
|
@ -125,7 +125,7 @@ master_doc = 'index'
|
|||
|
||||
# General information about the project.
|
||||
project = u'NanoGUI'
|
||||
copyright = u'2017, Wenzel Jakob'
|
||||
copyright = u'2019, Wenzel Jakob'
|
||||
author = u'Wenzel Jakob'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
|
|
@ -152,7 +152,7 @@ language = None
|
|||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
exclude_patterns = ['_build']
|
||||
exclude_patterns = ['_build', '_doxygen']
|
||||
|
||||
# The reST default role (used for this markup: `text`) to use for all
|
||||
# documents.
|
||||
|
|
@ -170,7 +170,7 @@ exclude_patterns = ['_build']
|
|||
#show_authors = False
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
# pygments_style = 'sphinx'
|
||||
|
||||
# A list of ignored prefixes for module index sorting.
|
||||
#modindex_common_prefix = []
|
||||
|
|
|
|||
|
|
@ -179,11 +179,13 @@ Styling the Code
|
|||
Since we are using both Doxygen and Sphinx, we have access to a wealth of interesting
|
||||
documentation styling.
|
||||
|
||||
:From Doxygen:
|
||||
**From Doxygen**
|
||||
|
||||
You can use things like ``\throws``, ``\remark``, and even ``\ref`` to generate html
|
||||
links to other items.
|
||||
|
||||
:From Sphinx:
|
||||
**From Sphinx**
|
||||
|
||||
On the Sphinx side, you now have access to full reStructuredText syntax. This
|
||||
includes:
|
||||
|
||||
|
|
@ -226,121 +228,3 @@ documentation styling.
|
|||
|
||||
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
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
#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 <https://breathe.readthedocs.io/en/latest/doxygen.html#template>`_
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -7,11 +7,11 @@ C++
|
|||
There are effectively two ways that you can use NanoGUI in C++: have NanoGUI initialize
|
||||
and manage the OpenGL context (and GLFW), or you do it manually.
|
||||
|
||||
1. If you are letting NanoGUI take over, you **must** call :ref:`function_nanogui__init`
|
||||
1. If you are letting NanoGUI take over, you **must** call :func:`nanogui::init`
|
||||
before trying to do anything else. If you are managing OpenGL / GLFW yourself, make
|
||||
sure you **avoid** calling this method.
|
||||
|
||||
2. Create an instance of :ref:`class_nanogui__Screen` (or a derivative class you have
|
||||
2. Create an instance of :class:`nanogui::Screen` (or a derivative class you have
|
||||
written).
|
||||
|
||||
- NanoGUI managed OpenGL: call the explicit constructor.
|
||||
|
|
@ -22,17 +22,17 @@ and manage the OpenGL context (and GLFW), or you do it manually.
|
|||
:func:`nanogui::Screen::setVisible` and :func:`nanogui::Screen::performLayout`
|
||||
methods of your instance.
|
||||
|
||||
4. Now that everything is ready, call :ref:`function_nanogui__mainloop`.
|
||||
4. Now that everything is ready, call :func:`nanogui::mainloop`.
|
||||
|
||||
5. When all windows are closed, this function will exit, and you should follow it up
|
||||
with a call to :ref:`function_nanogui__shutdown`.
|
||||
with a call to :func:`nanogui::shutdown`.
|
||||
|
||||
:NanoGUI Managed OpenGL / GLFW:
|
||||
Refer to :ref:`nanogui_example_2` for a concise example of what that all looks like.
|
||||
|
||||
:Self Managed OpenGL / GLFW:
|
||||
Refer to :ref:`nanogui_example_3` for an as concise as possible example of what you
|
||||
will need to do to get the :ref:`class_nanogui__Screen` to work.
|
||||
will need to do to get the :class:`nanogui::Screen` to work.
|
||||
|
||||
|
||||
Python
|
||||
|
|
|
|||
Loading…
Reference in New Issue