readthedocs/sphinx-autoapi

A new approach to API documentation in Sphinx.

Sphinx AutoAPI

Sphinx AutoAPI is a Sphinx extension for generating complete API documentation without needing to load, run, or import the project being documented.

In contrast to the traditional Sphinx autodoc, which requires manual authoring and uses code imports, AutoAPI finds and generates documentation by parsing source code.

For more information, see the full documentation.

Getting Started

The following steps will walk through how to add AutoAPI to an existing Sphinx project. For instructions on how to set up a Sphinx project, see Sphinx's documentation.

Installation

AutoAPI can be installed through pip:

pip install sphinx-autoapi

Next, add and configure AutoAPI in your Sphinx project's conf.py.

extensions.append('autoapi.extension')

autoapi_dirs = ['path/to/source/files', 'src']

When the documentation is built, AutoAPI will now generate API documentation into an autoapi/ directory and add an entry to the documentation in your top level table of contents!

To configure AutoAPI behaviour further, see the Configuration documentation.

Contributing

Running the tests

Tests are executed through tox.

tox

Code Style

Code is formatted using black.

You can check your formatting using black's check mode:

tox -e formatting

You can also get black to format your changes for you:

black autoapi/ tests/

You can even get black to format changes automatically when you commit using pre-commit:

pip install pre-commit
pre-commit install

Release Notes

Release notes are managed through towncrier. When making a pull request you will need to create a news fragment to document your change:

tox -e release_notes -- create --help

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License. See the LICENSE.rst file for details.

sphinx-autoapi's Issues

Handle Javascript parsing with autoapi via jsdoc3

Moving from readthedocs/readthedocs.org#1291:

...
Here is an excerpt, which I created using jsdoc --explain lib/ical/binary.js in my working directory:

[
 {
        "comment": "/**\n   * @classdesc\n   * Represents the BINARY value type, which contains extra methods for\n   * encoding and decoding.\n   *\n   * @class\n   * @alias ICAL.Binary\n   * @param {String} aValue     The binary data for this value\n   */",
        "meta": {
            "range": [
                587,
                641
            ],
            "filename": "binary.js",
            "lineno": 22,
            "path": "/Users/kewisch/mozilla/github/ical.js/lib/ical",
            "code": {
                "id": "astnode100000009",
                "name": "Binary",
                "type": "FunctionDeclaration",
                "paramnames": [
                    "aValue"
                ]
            },
            "vars": {
                "this.value": "ICAL.Binary#value"
            }
        },
        "classdesc": "Represents the BINARY value type, which contains extra methods for\nencoding and decoding.",
        "kind": "class",
        "alias": "ICAL.Binary",
        "params": [
            {
                "type": {
                    "names": [
                        "String"
                    ]
                },
                "description": "The binary data for this value",
                "name": "aValue"
            }
        ],
        "name": "Binary",
        "longname": "ICAL.Binary",
        "memberof": "ICAL",
        "scope": "static"
    }, 
    ...
]

Is it possible to distinguish also into enumerations, operators, ..., and properties?

Currently, autoapi differentiates 4 kinds:

• class
• exception
• method
• variable
• function

Is it possible to also differentiate into:

• enumeration
• operator
• property
• staticmethod
• classmethod

autoapi already lists exceptions in a different category, if a class is inheriting from Exception. This could be extended to also cover enumerations, so we can create a more precise header in the documentation for all object kinds in a module.

This is the current output:

For methods in a class I would like to have the opportunity to create subgroups for:

• operators
• properties
• static methods
• class methods

It should also be possible to select:

• public,
• protected, and
• private methods.

Help for installing sphinx-autoapi on ubuntu

Sorry if this is the wrong place. I'm trying to install sphinx-autoapi on ubuntu 14.04, and I'd like help.

I had to add the --pre flag to pip install sphinx-autoapi, but sphinx-build still says that autoapi.extension is missing.

Do I have the right names? Thanks for your help.

Snippet of installation log:

$ pip install sphinx-autoapi --pre
...

$ python .../test/bin/sphinx-build -v -v -T -b readthedocs -d _build/doctrees-readthedocs -c /www/docs/ -D language=en . _build/html
Running Sphinx v1.3.5
[app] setting up extension: 'autoapi.extension'
Original exception:
Traceback (most recent call last):
  File "/usr/local/lib/python2.7/dist-packages/sphinx/application.py", line 431, in setup_extension
    mod = __import__(extension, None, None, ['setup'])
ImportError: No module named autoapi.extension


Traceback (most recent call last):
  File "/usr/local/lib/python2.7/dist-packages/sphinx/cmdline.py", line 243, in main
    opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
  File "/usr/local/lib/python2.7/dist-packages/sphinx/application.py", line 144, in __init__
    self.setup_extension(extension)
  File "/usr/local/lib/python2.7/dist-packages/sphinx/application.py", line 435, in setup_extension
    err)
ExtensionError: Could not import extension autoapi.extension (exception: No module named autoapi.extension)

Extension error:
Could not import extension autoapi.extension (exception: No module named autoapi.extension)

Tests broken and missing with new pydocstyle parser

Add tests around argument parsing, fix others.

Raised in #78

.NET generic references with backtick aren't escaped properly

Seeing a lot of this in output:

:dotnet:`Foobar`1`

Move build outputs under _build

It would be nice if the intermediate build outputs from autoapi were put under the _build folder. That way make clean would clean them out without having to modify anything.

PHPdoc support

Would it be possible to get serialized output from phpdoc?

Display .NET enum values in order

.NET enum values should be displayed in a reasonable order. Ex numerical order. Currently the order looks a bit arbitrary. See https://docs.asp.net/projects/api/en/latest/autoapi/Microsoft/Extensions/Logging/LogLevel/index.html#fields for an example.

Add support for docfx.json

The .NET mapper will currently scan for project.json/MSBUILD files and add them to the command-line call. This becomes problematic for large projects because you can hit limits on the command-line length.

The docfx tool supports specifying which projects you want to generated api refs for using a docfx.json file. If this file is found it should be used instead of scanning specific project files.

Improved slugging and slug dedulpication

For proper slugging, we should be running some deduplication checks inside the mapper instead of just transform magic.

From #23

Generated .NET API docs for a type should include the namespace and assembly name

Existing MSDN docs for .NET types include the namespace and assembly name near the top of the page. For example https://msdn.microsoft.com/en-us/library/system.console(v=vs.110).aspx:

It would be great if autoapi did this as well. I believe the metadata is already provided by docfx.

Constructs are leaking

Functions and others seem to have their own directory in our output.

http://www.pydoc.io/pypi/requests-2.11.1/autoapi/unquote_header_value/index.html

Refs #78

Improve slugging

As per discussion in #20, make proper slugging on filename output.

Support additional options to .NET constructors from domain changes

The domain was updated to handle and display extra options on objects:

• :protected:
• :public:
• :static:

As well as property options:

• :getter:
• :setter:

And field options:

• :adder:
• :remover:

Add support for yaml fields to affect object options above and output in templates.

Allow for word characters directly next to inline XML tags in .NET XML doc comments

This is a valid .NET XML doc comment:

/// <summary>
/// Rewrites the provided <paramref name="context"/>s <see cref= "RewritingContext.SyntaxTree" />.
/// </summary>
/// <param name="context">Contains information on the rewriting of the syntax tree.</param>
/// <remarks>
/// To modify the syntax tree replace the <paramref name="context"/>s <see cref="RewritingContext.SyntaxTree"/>.
/// </remarks>
void Rewrite(RewritingContext context);

Note the s next to the paramref in the summary. The generated rst generates a warning because of word characters directly next to the double back ticks:

Rewrites the provided ``context``s :dn:prop:`Microsoft.AspNet.Razor.Parser.RewritingContext.SyntaxTree`\.

Instead I believe an escaped space should be generated between the parameter and directly neighboring text:

Rewrites the provided ``context``\ s :dn:prop:`Microsoft.AspNet.Razor.Parser.RewritingContext.SyntaxTree`\.

Fix python templates

Templates are overly verbose, remove extraneous headings and find a more digestible way to list elements.

Raised in #78

Add mapper filename handling

Add filename determination for each mapper as per discussion at #9 (diff)

.Net and docfx on mono mac

Hello,

Thank you for this extension that looks promising.

I'm trying to run the dotnetexample but I'm stuck with the docfx install.

I'm on mac OSX and I don't know how to get such installation working with Nuget.

Would you mind giving me an advice ?
Many thanks,
Lionel

Add Gitter Chat

Or Skype, or Slack, or anything else.

I'm having trouble building the docs from JS, and there's really so much issues along the way that I feel it's silly to report them as bugs.

It'd be great to be able to consult with the developers in a chat.

Provide a way to convert docfx map files to intersphinx inventories

See dotnet/docfx#123

How to handle generic type syntax reference links

Currently, a lot of links are written to point to something like:

:dn:class:`FooBar\`1`

But definitions look like this:

.. :dn:class:: FooBar<Foo>

.. :dn:class:: FooBar<Bar>

So, in the case of only a single match, we can add a parameter to the class definition directive to specify the id to use.

But what do we do in the case of multiple matches, like above? The reference would link to a group? Only to the first match?

No autoapi_dir config value

When I try to use the autoapi extension I get this error complaining that there is no autoapi_dir config value specified:

# Sphinx version: 1.3.1
# Python version: 3.5.1 (CPython)
# Docutils version: 0.12 release
# Jinja2 version: 2.8
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\sphinx\cmdline.py", line 244, in main
    opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\sphinx\application.py", line 188, in __init__
    self._init_builder(buildername)
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\sphinx\application.py", line 250, in _init_builder
    self.emit('builder-inited')
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\sphinx\application.py", line 497, in emit
    results.append(callback(self, *args))
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\autoapi\extension.py", line 32, in run_autoapi
    normalized_dirs.append(app.config.autoapi_dir)
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\sphinx\config.py", line 368, in __getattr__
    raise AttributeError('No such config value: %s' % name)
AttributeError: No such config value: autoapi_dir

This code in extension.py appears to be the problem:

    # Make sure the paths are full
    normalized_dirs = []
    for path in app.config.autoapi_dirs:
        if os.path.isabs(path):
            normalized_dirs.append(app.config.autoapi_dir)
        else:
            normalized_dirs.append(
                os.path.normpath(os.path.join(app.confdir, path))
            )

I think app.config.autoapi_dir should be path.

Warning: Unknown type, when generating docs for C# operator overloads

C# allows you to overload operators (like equality and inequality). I'm getting Warning: Unknown type warnings when generating API docs for types with C# operator overloads:

WARNING: Unknown type: 
{
  'href': 'Microsoft.AspNet.Http.FragmentString.yml', 
  'parent': 'Microsoft.AspNet.Http.FragmentString', 
  'uid':  Microsoft.AspNet.Http.FragmentString.op_Equality(Microsoft.AspNet.Http.FragmentString,Microsoft.AspNet.Http.FragmentString)', 
  'source': {
    'remote': {
      'repo': 'https://github.com/aspnet/apidocs', 
      'path': 'httpabstractions/src/Microsoft.AspNet.Http.Abstractions/FragmentString.cs', 
      'branch': 'master'}, 
      'path': 'httpabstractions/src/Microsoft.AspNet.Http.Abstractions/FragmentString.cs', 
      'startLine': 126
    },
  'type': 'Operator', 
  'name': 'Equality(FragmentString, FragmentString)',
  'syntax': {
    'parameters': [
      {'id': 'left', 'type': 'Microsoft.AspNet.Http.FragmentString'}, 
      {'id': 'right', 'type': 'Microsoft.AspNet.Http.FragmentString'}], 
    'content.vb': 'Public Shared Operator =(left As FragmentString, right As FragmentString) As Boolean', 
    'content': 'public static bool operator ==(FragmentString left, FragmentString right)', 
    'return': {
      'type': 'System.Boolean', 
      'description': None
    }
  }, 
  'namespace': 'Microsoft.AspNet.Http', 
  'fullName': 'Microsoft.AspNet.Http.FragmentString.Equality(Microsoft.AspNet.Http.FragmentString, Microsoft.AspNet.Http.FragmentString)', 
  'id': 'op_Equality(Microsoft.AspNet.Http.FragmentString,Microsoft.AspNet.Http.FragmentString)',
  'assemblies': ['Microsoft.AspNet.Http.Abstractions']
}

I'm using 1.0.0-rc1-final of DNX the latest docfx dev build from: https://myget.org/f/docfx-dev/api/v3/index.json. I see this error when generating docs for the master branch of the https://github.com/aspnet/httpabstractions repo.

"Parsing signature failed" warning when type has C# indexers

C# has a feature where you can define custom indexers for a type. Indexers allow instances of a class or struct to be indexed just like arrays. Indexers resemble properties except that their accessors take parameters.

When I run autoapi on a type that defines an indexer I get the following warning:

WARNING: Parsing signature failed: "ClassLibrary3.TagHelperAttributeList.Item[System.String]"

Here is the type:

    public class TagHelperAttributeList
    {
        /// <summary>
        /// Gets the first <see cref="TagHelperAttribute"/> with <see cref="TagHelperAttribute.Name"/> matching
        /// <paramref name="name"/>. When setting, replaces the first matching
        /// <see cref="TagHelperAttribute"/> with the specified <paramref name="value"/> and removes any additional
        /// matching <see cref="TagHelperAttribute"/>s. If a matching <see cref="TagHelperAttribute"/> is not found,
        /// adds the specified <paramref name="value"/> to the end of the collection.
        /// </summary>
        /// <param name="name">
        /// The <see cref="TagHelperAttribute.Name"/> of the <see cref="TagHelperAttribute"/> to get or set.
        /// </param>
        /// <returns>The first <see cref="TagHelperAttribute"/> with <see cref="TagHelperAttribute.Name"/> matching
        /// <paramref name="name"/>.
        /// </returns>
        /// <remarks><paramref name="name"/> is compared case-insensitively. When setting,
        /// <see cref="TagHelperAttribute"/>s <see cref="TagHelperAttribute.Name"/> must be <c>null</c> or
        /// case-insensitively match the specified <paramref name="name"/>.</remarks>
        /// <example>
        /// <code>
        /// var attributes = new TagHelperAttributeList();
        ///
        /// // Will "value" be converted to a TagHelperAttribute with a null Name
        /// attributes["name"] = "value";
        ///
        /// // TagHelperAttribute.Name must match the specified name.
        /// attributes["name"] = new TagHelperAttribute("name", "value");
        /// </code>
        /// </example>
        public TagHelperAttribute this[string name]
        {
            get
            {
                return null;
            }
            set
            {

            }
        }
    }

Attached is the generated metadata from docfx.
yaml.zip

.NET toctrees use unix path separators in templates

TOC tree includes in templates should determine the correct separator to use.

Invalid View on GitHub links

When I ran autoapi I got "View on GitHub" links that looked like this:

`View on GitHub <https://github.com/aspnet/apidocs/blob/master/aspnet/antiforgery/src/Microsoft.AspNet.Antiforgery/AntiforgeryContext.cs>`_

That I then had to fix up like this:

`View on GitHub <https://github.com/aspnet/antiforgery/blob/master/src/Microsoft.AspNet.Antiforgery/AntiforgeryContext.cs>`_  

Confusing formatting of .NET generic types

Ported from dotnet/AspNetCore.Docs#1337. I fixed up the generated rst manually, so you will need to look at the commit history to see the original issue.

In the ASP.NET Core API reference, generic types are formatted in a confusing way. For example, the return type of ConfigurationProvider.Data shows as:

System.Collections.Generic.IDictionary<System.Collections.Generic.IDictionary`2>{System.String<System.String>, System.String<System.String>}

Instead, this should show just like in the code just below:

IDictionary<string, string>

Or maybe with namespaces included:

System.Collections.Generic.IDictionary<string, string>

How do we want to display linked type parameters?

Currently, with a patched sphinx domain, the display looks like such on the go support branch:

This is the traditional output for documenting parameters in sphinx, however sphinx expects parameter listing with a description. Parameter types could be listed inline in the signature as well though, with some modifications to the sphinx golang domain, but this is a pattern that deviates slightly from traditional parameter listing.

The other option is to expect some form of parameter description in the member documentation markup.

Support backend-specific cleanup

The .Net backend generated temp files which we don't currently cleanup. We should add support for per-backend cleanup, since the main code shouldn't need to know about the temp files.

Add Java support

More comprehensive python mapper test

The current test is just a vendored module, replace with something that might include failing cases, and actually test for output.

Raised in #78

Asterisks in .NET XML doc comments result in RST errors

This method:

/// <summary>
/// Creates a <see cref="IChangeToken"/> for the specified <paramref name="filter"/>.
/// </summary>
/// <param name="filter">Filter string used to determine what files or folders to monitor. Example: **/*.cs, *.*, subFolder/**/*.cshtml.</param>
/// <returns>An <see cref="IChangeToken"/> that is notified when a file matching <paramref name="filter"/> is added, modified or deleted.</returns>
IChangeToken Watch(string filter);

Results in this error:

C:\Users\daroth\Documents\GitHub\apidocs\docs\autoapi\Microsoft\AspNet\FileProviders\IFileProvider\index.rst:107: WARNING: Inline emphasis start-string without end-string.

Here's the generated RST:

:param filter: Filter string used to determine what files or folders to monitor. Example: **/*.cs, *.*, subFolder/**/*.cshtml.

NameError: name 'basestring' is not defined

# Sphinx version: 1.4.1
# Python version: 3.5.1 (CPython)
# Docutils version: 0.12 release
# Jinja2 version: 2.8
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\sphinx\cmdline.py", line 243, in main
    opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\sphinx\application.py", line 197, in __init__
    self._init_builder(self.buildername)
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\sphinx\application.py", line 269, in _init_builder
    self.emit('builder-inited')
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\sphinx\application.py", line 536, in emit
    results.append(callback(self, *args))
  File "c:\users\daroth\appdata\local\programs\python\python35\lib\site-packages\autoapi\extension.py", line 31, in run_autoapi
    if isinstance(autoapi_dirs, basestring):
NameError: name 'basestring' is not defined

Appveyor config is hosed

I tried a few fixes, but seem to continue to receive additional errors.

---------------------------- Captured stderr call -----------------------------
Cloning into 'C:\projects\sphinx-autoapi\tests\dotnetexample\example/Identity'...
fatal: unable to access 'https://github.com/aspnet/Identity/': error setting certificate verify locations:
  CAfile: C:/Program Files/Git/mingw64/libexec/ssl/certs/ca-bundle.crt
  CApath: none
===================== 1 failed, 18 passed in 2.86 seconds =====================
ERROR: InvocationError: 'C:\\projects\\sphinx-autoapi\\.tox\\py27\\Scripts\\py.test.EXE' 

Improve handling of <see cref="..." /> and <paramref name="..." /> tags in .NET XML doc comments

The <see cref"..." /> tags in .NET XML doc comments frequently show up the generated rst or sometimes get completely removed. In some cases <paramref name="..." /> tags are also not handled. Take this example:

         /// <summary> 
         /// Get the security stamp for the specified <paramref name="user" />. 
         /// </summary> 
         /// <param name="user">The user whose security stamp should be set.</param> 
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> used to propagate notifications that the operation should be canceled.</param> 
         /// <returns>The <see cref="Task"/> that represents the asynchronous operation, containing the security stamp for the specified <paramref name="user"/>.</returns> 
         public virtual Task<string> GetSecurityStampAsync(TUser user, CancellationToken cancellationToken = default(CancellationToken))
         { 
             return Task.FromResult("abc"); 
         } 

The generated rst looks like this:

    .. dn:method:: ClassLibrary3.UserStore<TUser, TRole, TContext, TKey>.GetSecurityStampAsync(TUser, System.Threading.CancellationToken)



        Get the security stamp for the specified ``user``.




        :param user: The user whose security stamp should be set.

        :type user: {TUser}


        :param cancellationToken: The  used to propagate notifications that the operation should be canceled.

        :type cancellationToken: System.Threading.CancellationToken
        :rtype: System.Threading.Tasks.Task{System.String}
        :return: The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous operation, containing the security stamp for the specified <paramref name="user" />.

A few things to note:

• The paramref is handled in the summary, but not in the return value description.
• The <see cref="T:System.Threading.Tasks.Task" /> element is left in the return value description instead of being handled.
• The <see cref="CancellationToken"/> element is completely removed from the description for the user parameter without leaving any text at all.

Error, No API objects exist

I'm having problem getting the autoapi to work with my code. Then I tried from the .net test directory, but i'm getting the same error there. Any idea what I'm missing ?

make html
The system cannot find the path specified.
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.3.5
loading pickled environment... not yet created
[AutoAPI] Loading Data
[AutoAPI] Reading files... [100%] C:\tmp\sphinx-autoapi\tests\dotnetexample\example\Identity\src\Microsoft.AspNetCore.Identity.EntityFrameworkCore\project.json
[AutoAPI] Mapping Data
[AutoAPI] Rendering Data

Extension error:
No API objects exist. Can't continue
make: *** [html] Error 1

Edit on Github link is broken on autoapi generated .NET docs

We are linking to our generated url, not the url provided by docfx:

source:
  remote: *o0
  path: src/Microsoft.AspNet.Identity/IUserClaimStore.cs
  startLine: 33

They might also be broken on other languages.

The dotnet mapper should restore packages using `dnu restore` before running docfx

Docfx needs the packages to be restored in order to generate complete metadata. For example, if you look at the inheritance hierarchy for IdentityDbContext you will see that the base DbContext type doesn’t have a namespace. That’s because this type is defined in a separate package and docfx didn’t have access to its metadata.

Generated .NET API ref docs should include the NuGet package ID

The generated .NET API ref docs for types should include the source NuGet package ID. The package ID is not currently available in the metadata documents generated by docfx. This ask is tracked by dotnet/docfx#139.

Types listed on a namespace page should note include the namespace in the type name

Currently the generated namespace pages list the available types in that namespace using the full name of the types (including the namespace).

This is very redundant as the namespace is indicated at the top of the page. Instead the types should be listed using only the local name of the type without the namespace.

Consider just using setuptools

Setuptools is widely required in the Python world, so we can likely drop the distutils block in our setup.py.

Supporting localization in generated documentation

At what point would localization happen in the generation process, and how can we make contribution to localization on generated documentation an open source effort?

No link generated for return types

When I run autoapi on the master branch of the ASP.NET JsonPatch repo, I don't get links generated for return types.

For example, the OperationType property on the OperationBase type returns an OperationType enum. The generated RST looks like this:

    .. dn:property:: Microsoft.AspNet.JsonPatch.Operations.OperationBase.OperationType


        :rtype: Microsoft.AspNet.JsonPatch.Operations.OperationType

The generated docs contain the OperationType enum, but the generated return type doesn't link to it.

Add POD parsing support to autoapi

Moving discussion on readthedocs/readthedocs.org#1319 here for the time being.

I started tackling this problem a few months ago and have a working prototype. Putting this here for some feedback on supporting just pulling out POD blocks from source pm files.

So, parsing POD (or another markup lacking semantics for language constructs/etc) is useful for prose documentation, but without semantics for language constructs, these formats are only proxies to HTML and text output. At best, we could parse every heading for something that looks like a function/method/etc, but even then, good luck getting everyone to write in a systematic format.

A solution to this is to use a markup with directives for adding semantic meaning to blocks: rST. rST is much more powerful, providing all of the structure for defining language constructs and linking them easily. This would be a breaking change to hosting on CPAN/MetaCPAN, but with a helper like a Build.PL trigger to compile POD on release, this could be likely easily be preserved.

Your source would end up looking something like:

package Foo::Bar;

=begin rst
.. pl:package:: Foo::Bar

.. pl:function:: foo(arg1, arg2, arg3)
    :param arg1: First argument
    :type arg1: str
    :param arg2: Second argument, no type
    :param arg3: Third argument
    :type arg3: []

    This is a function for doing foo
=cut
sub foo() {
    ...
}

=pod
.. pl:function:: bar(arg1)

    Calls :pl:func:`foo` with :pl:data:`arg1`

=end rst
sub bar {
    ...
}
1;

Open to comments, input, and other crazy ideas here.

Regression with code sample in XML

Literal syntax output is:

Something something ``code ``something something.

This causes warnings and is invalid rst, it should be:

Something ``code`` something

Default output folder for docfx changed to _site

Looks like the .NET mapper assumes that the default output folder will be _api_, but it recently go changed to _site. The .NET mapper should probably explicitly specify the output folder when running docfx to make sure it can find the output metadata.

Python mapper argument parsing bugs and documentation

We aren't verifying input from pydocstyle in the Python mapper and the argument splitting is a just a simple split on ,. Some failing cases (not verified, we still need tests/docs around the pydocstyle integration):

def foo(bar_a, bar_b,
        bar_c, bar_d):

def foo(bar, baz={'a': 'a', 'b': 'b'})

Raised in #78

Handling generic types

Generic types in the docfx metadata format are identified using a spec identifier format that represents generic type parameters with curly brackets. This format is for referencing purposes in the metadata documents, but it is showing up in the rendered docs (ex see the user argument and the return value of the [GetSecurityStampAsync](https://docs.asp.net/projects/api/en/latest/autoapi/Microsoft/AspNet/Identity/EntityFramework/UserStore-TUser-TRole-TContext-TKey/index.html?highlight=getsecuritystampasync#Microsoft.AspNet.Identity.EntityFramework.UserStore<TUser, TRole, TContext, TKey>.GetSecurityStampAsync) method:

Instead these "spec identifiers" should be resolved to their user friendly names for display purposes. I believe this data is available for lookup in the references section of the generated metadata documents:

- uid: System.Threading.Tasks.Task{System.String}
  parent: System.Threading.Tasks
  definition: System.Threading.Tasks.Task`1
  name: Task<String>
  name.vb: Task(Of String)
  fullName: System.Threading.Tasks.Task<System.String>
  fullName.vb: System.Threading.Tasks.Task(Of System.String)

.NET constructs sometimes display side by side

This might be an autoapi issue, or could be a theme issue. I believe the issue is triggered when the element name is short and there is no documentation to expand the element out to full width. We could be missing some HTML elements expected by the theme HTML here.

Deduplicate verbose headings in python templates

Templates currently output an explicit "Package ...", "Module ..." for objects. This makes for ugly output when the module being documented starts off with a docstring:

"""
modulename.submodule
--------------------

Things
"""

As we end up with:

Module submodule
================

modulename.submodule
--------------------

The easiest way around this issue is to not output a header if there is a docstring. The more complete way to fix this issue might be to parse out the docstring, removing the first heading?