Output File Paths

[karolswdev]

Hi Dinesh,

I'm really confused with your documentation. Why is the output parameter essentially used as an input parameter? Doesn't make sense. In my opinion, you should introduce an input parameter that takes which files are to be parsed and an output parameter that writes them to the desired paths/files.

I'd like to hear your opinion on this.

[dineshsonachalam]

Hi @karolswdev,

Input parameters:

The input parameters are part of the markdown file content. You need to add markers in your README.md that will tell markdown-autodocs where to insert the code snippet.

Output parameters (file paths):

Generates & updates markdown content (like your README.md) from external or remote files.

I don't feel like there is a need to introduce a new input parameter that takes which files are to be parsed and an output parameter that writes them to the desired paths/files.

[karolswdev]

Dinesh. I'm talking about input parameters to your tool, not the markdown. I understand how your (great) tool works, I just think your choice of params is wrong. -o means 'output' in all the tooling I've ever used in my life. Given the following scenario:

• 🗄️ MyFile.md

MyFile.md has several sections to be filled up by markdown-autodocs.

You can't issue the following:

user@host % markdown-autodocs -c code-block -o MyFileParsed.md

Because your tool will say there's no such file found. But in reality, all tooling uses -o to declare what the output of the operation should be. If you want to be consistent with it, introduce a -i parameter that will take a relative file path (.md) to be parsed and -o for what the newly written file's name should be.

All I'm saying is:

-o is simply wrong, the way it's used now

Can be changed to -i and the entire logic could stay the same, or... you could think about re-introducing -o to let people have 'templates' (for -i) and 'outputs' (for -o)

BTW: Take a look here - I dockerized your tool for my own sake.