Configuration#

sphinx-csharp reads these options from conf.py.

External Links#

A type that your pages do not describe links to its external documentation, when the type map below lists it. The System types link to the Microsoft documentation:

.. cs:function:: List<string> Split (string text)

List<string> Split (string text)

Add the types of another library with sphinx_csharp_external_type_map, and the pages that document them with sphinx_csharp_external_search_pages:

sphinx_csharp_external_search_pages = {
    'widgets': ('https://example.com/api/%s.html', 'https://example.com/search?q=%s'),
}
sphinx_csharp_external_type_map = {
    'widgets': {
        'Widgets.Controls': ['Button', 'Slider'],
    },
}

Each package has a page URL and a search URL, each with %s in place of the type. A generic type in the map has its number of generic parameters, as in IComparer-1, and takes precedence over a type of the same name without them. The values you set add to the defaults in extrefs_data.py.

sphinx_csharp_external_type_map#: The types of each external package, by namespace. Default: common .NET types as msdn, and Unity types as unity.

sphinx_csharp_external_search_pages#: The page URL and the search URL of each external package. Default: the Microsoft documentation as msdn, and the Unity scripting reference and manual as unity and unityman.

sphinx_csharp_external_type_rename#: Names to use in the URL of a type in place of its name, such as {'NativeArray': 'NativeArray_1'}. Default: the names of common generic types with their number of generic parameters, such as List-1 for List.

sphinx_csharp_unqualified_namespaces#: Namespaces whose types show without their namespace, such as ['UnityEngine']. The namespaces nested in them also count. Default: System and its namespaces.

sphinx_csharp_ignore_types#: Types that never link, such as ['Vector2']. Default: void, and the * and & of pointer and reference types.

sphinx_csharp_check_external_links#: Whether to request each external link as the build writes it, and use the search URL for a link that fails. The first connection error stops the checks. Default: False.

Other Options#

sphinx_csharp_add_namespace_names#: Whether the signature of an object in a namespace starts with the namespace, as in class Geometry.Canvas, like the add_module_names option of the Python domain. Members nested in a type show without it, and Breathe removes it. Default: False.

sphinx_csharp_compact_layout#: Whether to add the stylesheet of sphinx-csharp to the HTML pages. It puts the objects with no description close together, such as the values of an enum. Default: False.

sphinx_csharp_maximum_signature_line_length#: The length of a signature that puts each parameter on a line of its own. Default: None, which uses the maximum_signature_line_length option of Sphinx.

sphinx_csharp_multi_language#: Whether link titles start with C#, as in C# class: Geometry.Shape, for docs that describe several languages. Default: False.

sphinx_csharp_debug#: Log verbose debug output, for every category with True, or for a list of the categories parse, xref and external. Default: False.

Warnings#

Each warning has a type, so you can silence it with suppress_warnings:

suppress_warnings = ['cs.ambiguous']

Type	Warning
`cs.parse`	A signature is invalid, and shows as written.
`cs.duplicate`	An object is described more than once. References link to the description in the first page by name.
`cs.ambiguous`	A reference matches more than one object, and links to the first.
`cs.external`	An external link is ambiguous, fails the link check, or has no search page for its package.
`cs.config`	An option has an old name, which still works.
`cs.namespace`	A `namespace-pop` has no `namespace-push` to undo.

Run Sphinx with -n, or set nitpicky = True, to warn about each reference without a target.