Integration with breathe, various improvements, regexes, external linking

[rogerbarton]

Hi! I've been trying to get this to work with the sphinx breathe extension to document C# code with doxygen. This requires a working C# domain... I've had to make several changes and improvements, but its working quite nicely, have a look here. I use it for a C#/C++ Unity project.

1. Resolving references has improved
   • ignored built-in types and other strings, see IGNORE_XREF_TYPES
   • resolving to 'closest match' if the target is not inside any of the direct parent namespaces (this can still be improved), see resolve_xref
   • Searching for external links (previously just for MSDN), see below
2. External links can be added more easily
   • Direct API link is generated and checked if valid
   • If it is invalid a fallback link is used, usually a search
   • As a user, you need to specify the api link and a fallback link with %s for where to place the name
3. Improved parsing of signatures
   • more complicated types possible
   • Named regex groups for parsing (just makes it easier to extract the results)
4. Support for: events, interfaces, structs, proper variable parsing
5. Improved some of the rendering/visuals
   • use more of the sphinx addnodes over docutils nodes, also fixes some spacing issues
   • added nbsp for strings consisting of just spaces caf64fd
6. Soft failure if a signature does not match its regex ac522b1
   • the string is just rendered as is
7. Important:
   • changed domain name to 'cs' from 'csharp' 2e8e219
   • moved setup function to __init__ so we can import the extension with just sphinx_csharp instead of sphinx_csharp.csharp (its based on how breathe does it, not sure how good this is) 9cd500b
8. Use logger from sphinx to print info/warnings (found some deprecations with the current way of doing it) 9e7edbf
9. Test and integrate with breathe -> parses doxygen xml output
   • Handles some artifacts from doxygen, like generics being shown as template<T, U> MyFunc ()
   • ? being randomly added to the end of a name (no idea where this is coming from, doxygen might have interpreted my property as a nullable) 4398e31

Todo:

• xref resolution uses endswith in middle of type (so Material matches MyMaterial) 0a3fa65
• Move external types to the config and concatenate with defaults 8c14a69 14fdafd
  • Also put in a debug/verbose option in the config 389f01c 37ac3d9
• Add some more test cases fb38af5

Future work:

• I'd recommend splitting the parsing/regexes into separate files, but I've left this out so there's less diffs. (It would make a lot of sense reducing the size/complexity of one file though)
• Figure out the correct combination for the domain vars: object_types, directives, roles (I have no idea how this is supposed to work)
• Improve property, attribute, indexer regexes/parsing

The current test cases seem to be working for me.

This PR is a dependency of another PR at the breathe repo: breathe-doc/breathe#550

fyi, I haven't really done much python and no sphinx at all before, so some stuff might be completely wrong/unconventionial. But I'm happy to fix that :)

[red8888]

Is this project dead? Or has it been moved or forked?

[jonnew]

I mean its been working for me. I think its just kinda done?

[ffes]

I think you are right @red8888, this repo is dead. This PR is open for over 1,5 years without any reaction of @djungelorm.

And @jonnew, when you look at the work that @rogerbarton has put into it, it definitely is not done. C# is a language where new feature are added every major release. When you use the file-scoped namespace introduced in C# 10, it breaks various parsers (maybe this one as well, haven't tested yet).

Maybe we should just open an issue named "This repo is dead", with a link to the repo of @rogerbarton if @djungelorm doesn't react any time soon.

[jonnew]

Lol I was not paying attention and actually thought this thread was on @rogerbarton's repo as that is the one I've been using.