Known issue: auto-generated index files for sections can clash on name

[FransBouma]

See: #61 for a PR that didn't get merged, but has a discussion about the issue.

See https://github.com/FransBouma/DocNet/pull/61#issuecomment-308660591 and https://github.com/FransBouma/DocNet/pull/61#issuecomment-308671862 about the details regarding this issue.

This issue can only be solved if it allows docnet to generate documentation which matches the output with the bug, as existing documentation relies on this bug and that can't change as that's too much work. I posted this tool on github for others to use as well, but not with the intention to give myself a lot of extra work (as the tool is used by our own documentation, and fixing this issue causes problems with our massive set of docs which rely on this documentation already as well as external links to the docs) due to changes in this application.

I know this issue is likely not affecting a lot of people but nevertheless it can be something you run into.

To really properly solve this, folders where files are generated in shouldn't be in the docnet.json file with the file description, instead the folders should be defined in the section header, so files in a section inherit the folder. Example of how it is now:

"Quick start guides" :
{
    "From Database to source code": 
    {
        "__index": "qsg\\dfscenario1\\index.md",
        "Create a project" : "qsg\\dfscenario1\\CreateProject.md",
        "Create entities based on a database": "qsg\\dfscenario1\\df_reverseengineer.md",
        "Generate source code":"qsg\\dfscenario1\\generatesourcecode.md"
    },

how it should be:

"Quick start guides" :
{
    "__folder": "qsg",
    "From Database to source code": 
    {
        "__folder": "dfscenario1",
        "__index": "index.md",
        "Create a project" : "CreateProject.md",
        "Create entities based on a database": "df_reverseengineer.md",
        "Generate source code":"generatesourcecode.md"
    },

The files then inherit the path from the container(s) they're in and this won't lead to clashes, as everything has a proper folder: auto-generated index files can be placed in the right folder as the containing container section has a folder (or inherits it from its parent, which then will be the same).

Additionally, "__folder" could be optional, in which case the folder is created from the section name.

This is a format change and behavior change and therefore does require a setting, to make it possible to switch between the behavior (so existing behavior is preserved).

[GeertvanHorrik]

This is just a theory so far, right? Or is this already implemented?

[FransBouma]

It's not implemented, but it is a design for how to fix it.

[GeertvanHorrik]

What do you prefer as setting name?

[GeertvanHorrik]

For example:

PathSpecification: "Full|Relative" (Full is existing behavior)

[FransBouma]

Sounds good :) (PathSpecification with those values). It's short and simple :)

[GeertvanHorrik]

For the first version I will just add the auto-generation of the folders. We can always expand, but need to get my head around where this needs to be implemented again.

[FransBouma]

Implemented