People turn to documentation for many different reasons, so it is important to consider the audience and what their needs are. What a person wants out of documentation depends on their background, what they want to do and their experience with the Katana system.
The initial experience for users will be focused around answering questions like "what does this system do?", "how can I test drive it?", "how can I install it?", while a developer looking to modify the Katana system itself, will be more interested in how the code is organized. And once someone gains experience, their focus will shift from tutorials and getting started guides, which help explain new concepts, to reference information, which serves as a reminder about details once a concept is known.
The documentation for the Katana system is organized in major groups, which answer specific questions:
- :ref:`getting-started`: How do I install the system? What are its basic requirements?
- :ref:`user-guides`: After I've installed Katana, how do I do common activities?
- :ref:`reference`: If I know the concept but am a little fuzzy on the details, can you give me a refresher?
- :ref:`contributing`: I'd like to improve to Katana itself. What should I know?
To build the documentation, set the -DBUILD_DOCS= option to either
internal or external and -DKATANA_LANG_BINDINGS=python cmake
options and then make the docs build target.
# internal documentation
cmake -S $SRC_DIR -B $BUILD_DIR -DKATANA_LANG_BINDINGS=python \
-DBUILD_DOCS=internal
# external documentation
cmake -S $SRC_DIR -B $BUILD_DIR -DKATANA_LANG_BINDINGS=python \
-DBUILD_DOCS=external
cd $BUILD_DIR
make docsFiles ending in -draft.[rst/ipynb] or -internal.[rst/ipynb] will not be
included in external facing documentation.
Whole directories ending in -draft/ or -internal/ will be omitted when
building external documentation.
Most documentation is written in Restructured Text (.rst) format, which is
similar to Markdown (.md) in spirit but has a slightly different syntax.
| Restructured Text | Markdown | |
| Inline code | The ``Foo`` function
|
The `Foo` function
|
| Code blocks | .. code-block:: python
def foo():
pass
|
```
def foo():
pass
```
|
| External links | Visit `my link <https://invalid/>`_
|
Visit [my link](https://invalid/)
|
| Internal links | .. _label:
See :ref:`label`
|
(Not applicable) |
| Sections | ====
Part
====
*******
Chapter
*******
Section
=======
Subsection
----------
Subsubsection
^^^^^^^^^^^^^
Paragraphs
""""""""""
|
# Level 1
## Level 2
### Level 3
#### Level 4
##### Level 5
###### Level 6
|
| Conditional Include | .. only:: internal
Text to only include when internal is set.
The only condition currently defined is |
(Not applicable) |
Guides on how to use Katana Graph in Python should be written as Jupyter
Notebooks. They will be parsed similar to Restructured Text (.rst) files.
This means that it doesn’t appear in a toctree (see index.rst),
but other pages can still link to it.
Orphaned notebookes require the following to be added to the notebook's JSON metadata:
"nbsphinx": {
"orphan": true
}API documentation is a form of reference information, usually embedded in code
files, and is targeted towards people who know the general concepts in question
but need some help with details or specifics, e.g., I have a Foo object but
what can I do with it?
The Katana codebase spans three languages: C++, Python and Go, but the principles of good API documentation are common regardless of language.
- Be precise. Good documentation is correct documentation. If the name of a function captures its semantics, there is no need to add more text. If a function has a simple name but subtle semantics, it probably deserves a better name and extensive documentation.
- Be humble. API documentation is written by the author of the code, but the author's assumptions are usually different than users' assumptions.
While it is possible to use markup in documentation text, e.g., C++ (Doxygen) supports a form of Markdown and Python (Sphinx) supports Restructured Text, it is best to keep text simple and communicate using basic text that can be read easily without being rendered by a separate documentation tool.
/// Foo returns the sum of a and b.
///
/// Foo rounds the result away from zero. That is: if the sum is negative,
/// Foo rounds towards negative infinity, and if sum is positive, Foo rounds
/// towards positive infinity.
///
/// As a side-effect, Foo updates an internal table of cached sums.
///
/// Foo can be used to simulate arithmetic on older processors like the Bar
/// M3000, which uses this uncommon rounding mode.
///
/// This function is not safe to call concurrently.
///
/// \param a The first addend
/// \param b The second addend
/// \return The sum of a and b
int32_t Foo(float a, float b) {
...
}API documentation should begin with /// and should appear only once per
symbol. If a symbol has a separate declaration and definition, put the API
documentation on the declaration.
In some cases, underlying Doxygen C++ parser may issues with parsing valid C++.
You can use the Doxygen macro DO_NOT_DOCUMENT to skip parsing of that
particular code block.
/// \cond DO_NOT_DOCUMENT
WeirdCXXSyntax();
/// \endcode DO_NOT_DOCUMENTdef foo(a: float, b: float) -> int:
"""
foo returns the sum of a and b.
Foo rounds the result away from zero. That is: if the sum is negative,
foo rounds towards negative infinity, and if sum is positive, foo rounds
towards positive infinity.
As a side-effect, foo updates an internal table of cached sums.
Foo can be used to simulate arithmetic on older processors like the Bar
M3000, which uses this uncommon rounding mode.
This function is not safe to call concurrently.
:param a: The first addend
:param b: The second addend
:return: The sum of a and b
"""
...// Foo returns the sum of a and b.
//
// Foo rounds the result away from zero. That is: if the sum is negative,
// foo rounds towards negative infinity, and if sum is positive, foo rounds
// towards positive infinity.
//
// As a side-effect, Foo updates an internal table of cached sums.
//
// Foo can be used to simulate arithmetic on older processors like the Bar
// M3000, which uses this uncommon rounding mode.
//
// This function is not safe to call concurrently.
func Foo(a, b float) int32 {
...
}The Effective Go Guide has further discussion on best practices for comments.