C# Domain for Sphinx with Breathe integration. Used to create ReadTheDocs style C# documentation.
See vr-modeling example end-product.
Idea:
- Generate Doxygen xml
- Convert this to Sphinx using breathe + sphinx-csharp
- Apply ReadTheDocs theme
- Write rst using the
cs
domain
Install using pip:
pip install git+https://github.com/rogerbarton/sphinx-csharp.git
To enable the extension, add the following to your conf.py:
extensions = ['sphinx_csharp']
See djungelorm#8 for usage/changes from upstream and also this rst example.
Various options can be set in the sphinx conf.py
. See __init__.py:setup()
for available options. Defaults for external references are indicated or in extrefs_data.py
.
See also csharp.py:apply_config(cls, config: Config)
for exact defaults.
Here are the default values for all available options:
# Are other languages used in the sphinx project, if yes add language (domain) prefix to reference labels
sphinx_csharp_multi_language = False
# Should generated external links be tested for validity
sphinx_csharp_test_links = False
# Remove these common prefixes from labels
sphinx_csharp_shorten_type_prefixes = [
'System.',
'System.IO',
...
]
# Do not create cross references for these standard/build-in types
sphinx_csharp_ignore_xref = [
'string',
'Vector2',
...
]
# How to generate external doc links, replace %s with type. Use the format
# 'package name': ('direct link to %s', 'alternate backup link or search page')
sphinx_csharp_ext_search_pages = {
'upm.xrit': ('https://docs.unity3d.com/Packages/[email protected]/api/%s.html',
'https://docs.unity3d.com/Packages/[email protected]/?%s'),
...
}
# Types that are in an external package. Use the format
# 'package name': {
# 'Namespace1': ['Type1', 'Type2'],
sphinx_csharp_ext_type_map = {
'unity': {
'': ['MonoBehaviour', 'ScriptableObject'],
'XR': ['InputDevice', 'InputDeviceCharacteristics'],
...
},
...
}
# [Advanced] Rename type before generating external link. Commonly used for generic types
sphinx_csharp_external_type_rename = {
'List': 'List-1',
'NativeArray': 'NativeArray_1',
...
}
# Debug options, these enable various verbose logging features.
sphinx_csharp_debug = False # enables all debug options
sphinx_csharp_debug_parse = False # enables all parsing options
sphinx_csharp_debug_parse_func = False
sphinx_csharp_debug_parse_var = False
sphinx_csharp_debug_parse_prop = False
sphinx_csharp_debug_parse_attr = False
sphinx_csharp_debug_parse_idxr = False
sphinx_csharp_debug_parse_type = False
sphinx_csharp_debug_xref = False
sphinx_csharp_debug_ext_links = False
See also this example.
See build scripts in test
. This is quite incomplete at the moment. The vr-modeling example will likely be most useful as a reference.
- Newer C# syntax that is not supported yet, see regexes at beginning of
csharp.py
for parsing - Incorrect xml reconstruction in breathe, see
def visit_*
in breatherender/sphinxrenderer.py
- e.g.
visit_variable
will create the signature that is given tocsharp.py
- e.g.