Hello Sphinx team, I have been trying to figure out how to write a new Sphinx domain for C#, based on the Python domain, but I'm having problems and I hope someone can help out.
>From what I gather I have to define a class for the domain, one for the index and a class for every directive and role I want to define. In C# there are namespaces (similar to modules in Python), class-likes (classes, structs, interfaces, enums) and members (member variables, properties, indexers). Classes and methods can be generic, i.e. have a type parameter. Here is what the declarations would look like: .. c#:namespace:: SuperFramework.Vectors :summary: Namespace for vector types in SuperFramework This is a longer description and so on. .. c#:method:: SuperFramework.Vectors.StuffVector<T> where T : Stuff :summary: Class for a collection of stuff. :typeparam T: The type of stuff. This is a longer description and so on. .. c#:method:: bool SuperFramework.Vectors.StuffVector<T>.FromThing<U>(U thing, int priority) where U : T :summary: Build a vector with default values. :typeparam T: The type of stuff. :typeparam U: The type of thing. :param priority: Some priority parameter. :returns: ``true`` on success This is a longer description and so on. I don't know if the number sign is valid as part of the domain prefix, I can change it to "cs" if needed. The directive options are taken from the official C# recommended documentation tags: https://msdn.microsoft.com/en-us/library/5ast78ax(v=vs.100).aspx For namespaces I have basically copied the Python module directive and renamed a few variables. Now I'm trying classes next. Typing the namespace into the declaration is ugly and when rendering the output (e.g. from Doxygeon or reading the .NET documentation) the namespace is not part of the declaration either. Would it be better to make it an option instead or should I extract it from the declaration via regex? The same for the parent, declaration or option? My guess is that declaration is easier to write but harder to read and process than an option. I'm looking at the Python domain right now, it does not define a "PyClass" class but a "PyClasslike" class for classes and exceptions. I guess that makes sense, the difference between the two is very small. The PyClasslike class is a child of the PyObject class, which is used by pretty much everything except modules. First question: what's up with the member variable ``doc_field_types``? I understand that it describes the fields/options the directive can have, but why are there so many in the base class? It doesn't make sense for a class to have return values or parameters or throw exceptions. Am I missing something? In the initialiser, what's the deal with the parameters ``name`` and ``names``, what's the difference? What does ``rolename`` and ``bodyrolename`` mean? What is the meaning of ``typenames`` and ``typerolename``? Second question, how does ``option_spec`` work? I see it maps an option to a function, but what is the purpose of the function? I hope these questions don't sound too noobish. -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
