Contributing to ASP.NET 5 Documentation

If you’re looking to learn ASP.NET 5, the best place to start today is the documentation site at It’s hosted on ReadTheDocs and the source is all in GitHub (/aspnet/docs). Since it’s all open source, you can contribute to the documentation yourself, which is a great way to learn ASP.NET 5 and help your fellow developers. I’ve created a short video that walks you through the process:

Check it out and let me know what you think.

  • Sean

    Thanks for the great overview Steve. It’s a great process but there’s one big thing that’s glossed over in the contrib guide: how are the RST code-block file/line references handled over time as the source repo changes? Is this process not able to be used with a live code base (and only examples)?

  • ardalis

    It’s definitely easiest with fixed samples. There is also api doc support if that’s what you’re looking for (see here for example: ).

    Using code blocks will decouple your docs from your codebase, but then of course they can get out of sync. There are other options for defining your code blocks, but at the end of the day you’re not going to get away from having to update your docs if your code changes substantially.

    More on literalinclude and code-block:

  • Nicolò Carandini

    Hi Steve, following your guide, when executing “make html” command, I got the error:

    Running Sphinx v1.4.6
    Extension error:
    Could not import extension sphinxcontrib.dotnetdomain (exception: No module named ‘sphinxcontrib’)

    I resolved with “pip install sphinxcontrib-dotnetdomain”.

    • ardalis

      Yes, the instructions have been updated since I made the video last year. I think what you list above is the only substantial change. There is also now a ‘make livehtml’ command available that is very helpful for running the live site locally.

      • Nicolò Carandini

        Now I’m stuck with an external ref Warning, treated as error:
        c:Gitaspnet-docsaspnetfundamentalsapp-state.rst:148: WARNING: dn:iface reference target not found: ~Microsoft.AspNetCore.Http.ISession

        something must be wrong with the intersphinx mapping or the ‘../common/api.inv’ file, because I do have the api folder with all the files.

        • Nicolò Carandini
        • Nicolò Carandini

          After a lot of work and investigation I haven’t found the solution so I just uninstalled everything and started again from scratch. And now works. Still puzzled, but happy that the “glitch” has gone away.