Question: Why \apidoc folder is needed

[svver]

I cannot find out why docfx creates \apidoc folder when executing docfx init.

[vicancy]

This is the suggested place for putting overwrite markdown files, e.g. https://github.com/dotnet/docfx/blob/dev/Documentation/apispec/YamlUtility.md. overwrite markdown files are files with YAML headers to provide more information to the API generated from source code, as shown in http://dotnet.github.io/docfx/api/Microsoft.DocAsCode.Common.YamlUtility.html.

Currently documentation on this area is still missing, and we are working on it.

[svver]

Thank you, @vicancy! I've tried to create few overwrite .md-files. Nice that it works not only for types, but also for members and namespaces.
Can I help with docs on this feature? Is there a list of topics that need to be covered, or an article that needs to be augmented?

[vicancy]

It would be great! I've drafted one in #233 . Please feel free to add comments!

[Shazwazza]

Hi, @svver you mentioned that you have got the overwrite functionality working for namespaces, can you explain a little more about this and how you have it working? I would really like to have this feature so we can add documentation at the namespace level. Any help is much appreciated!

[vicancy]

@Shazwazza overwrite documents can apply to namespaces, http://dotnet.github.io/docfx/tutorial/intro_overwrite_files.html, For example, for namespace System, adding summary to it with overwrite file:

---
uid: System
summary: *content
---
Here is the summary for summary namespace in markdown syntax...

[Shazwazza]

@vicancy thanks for getting back to me. I'm using version 2.19.2 and no matter what I try I cannot get anything output for the Namespace. I can successfully merge or replace info at a class level but not for a namespace.

Here's a screenshot which shows what I'm doing

In that screenshot you'll see the Lucene.Net.Index.AtomicReader.md file and with that it overwrites information for that class, but the namespace link isn't successful.

Any ideas?

[vicancy]

@Shazwazza The overwrite file format looks good to me. Could you share your docfx.json? Is the file added to the overwrite section?

[Shazwazza]

@vicancy Yes the docfx.json file is here: https://github.com/Shazwazza/lucenenet/blob/docfx-apidocs/apidocs/docfx.json the overwrite section is including all files listed in "apispec/**.md" and there are 2 test files in that folder here: https://github.com/Shazwazza/lucenenet/tree/docfx-apidocs/apidocs/apispec , the AtomicReader one work (which is a class) but the Lucene.Net.Index one doesn't work which is the namespace

[vicancy]

@Shazwazza https://github.com/Shazwazza/lucenenet/edit/docfx-apidocs/apidocs/apispec/Lucene.Net.%E2%80%8BIndex.md According to the edit page, is there a zero-width space in between the uid?

[Shazwazza]

@vicancy You are an absolute legend! This must have come from some copy and paste issue and I certainly didn't that problem. This works as advertised. Thanks again :)