DocFx questions

[JamesNK]

Hi! I'm happy that MS is finally making some documentation looks again. Right now I'm using Sandcastle and I had some questions:

1- The uses of it I've seen of DocFx so far are focused on generating the entire site rather than a section. I already have an ASP.NET MVC site and the documention is just a section. I'm guessing the template can just be updated to ignore the top level TOC file then the static files are uploaded to a subdirectory and linked to as usual?

While that approach works, a nice to have would be if the process that generates HTML files from markdown and templates could be turned into a library. ASP.NET sites could use it to generate HTML on the fly and embed in the layout system of an ASP.NET MVC site.

2- I use Sandcastle's code snippet plugin a lot. In your documentation it mentions referencing a file and then either specifying line numbers or a tag. What is a tag in C#? Sandcastle lets you specfiy a C# #region and that content is imported

<code lang="cs" source="..\Src\Newtonsoft.Json.Tests\Documentation\Samples\Json\CustomJsonReader.cs" region="Usage" title="Usage" />

I like #region because it is part of the language and messing them up results in a compilation error.

3- Can conceptual and API documentation be combined in a single TOC? That is what I'm doing currently with Sandcastle: http://www.newtonsoft.com/json/help/html/Introduction.htm (API documentation expands at the bottom)

4- Can the location of the templates be specified in the config file? One thing that bugs me about Sandcastle is the templates have to site inside Sandcastle's install directory so it makes it difficult to have them under source control.

5- I like the github links in the API documentation. In the DoxFx docs it is linking to the master branch. Can it link to a tag? Otherwise the docs and master will get out of sync from dev changes.

6- The DocFx API docs don't generate links to MSDN for BCL types, e.g. string. Will it support linking to other documentation websites for third-party types?

7- There are no pages generated for API members. Is this an option?

[chenkennt]

Hi JamesNK,

1. Yes, DocFX allows you to customize the template, you can modify the template to remove the nav bar and integrate with your ASP.NET web site.

2. Currently the tag in C# looks like this:

   // <snippet1>
   // your code snippet...
   // </snippet1>

   Using region is a good idea, we will add this support later.

3. Currently no, conceptual and API has to be in separate TOC. But we have a feature on our list to combine all TOC files to output a single TOC.

4. Yes, you can look our documentation, which is also generated by DocFX, the location of template is specified in docfx.json:
   https://github.com/dotnet/docfx/blob/dev/Documentation/docfx.json
   And the files are stored in the repo:
   https://github.com/dotnet/docfx/tree/dev/Documentation/template

5. Currently the link points to branch where you build the documentation. This is on purpose because we want reader to be able to directly edit on the github if he wants to improve the triple slash comments in code. But we'll also add commit information to the output so that you can easily customize the template to make the link point to a particular commit.

6. Yes, this is already supported. We have an external reference feature that allows you import the information of third-party API docs and reference them in your own documentation. To reference .NET BCL types, you need to install a nuget package that contains the all BCL types on MSDN, and reference them in your docfx.json.

7. Currently this is not an option. We switched from member level page to type level page because most of the member pages are very short so we think it's better to combine them into a single one. Let me know if you think member page is important, we'll consider to add that support later.