load a config to customize output

[axelhahn]

Hi Stéphane

I was on search for generation of markdown for class files (an html help from it I will generate with Daux.io). I also liked the idea to add the output between 2 markers of an existing file.

Because the markdown output was hartcoded I put it into an extra file.
To be customized I added a dist file that overrides the default config.

Regards,
Axel

[vphantom]

Hi there, and thank you for contributing!

I'd prefer if the absence of a config file would trigger the default behavior, but otherwise I think that's a great idea. This is my first PR on here so I'm not too sure how I could propose changes inside this PR; I'll look into that as soon as possible.

[axelhahn]

Hi,
the initial point was to render a table for @params data for variable, type and description instead of a list. At this point came the idea that someone else wants to customize the md output a bit ...
So I will rollback my version to be able to contribute somehting. (If it is OK I put the table into it)

[vphantom]

Actually I really like the idea of the configuration file as you've done it. The only thing I would change is that I would look for a .docblox2md.js file and load it, but if it's missing (currently the else on line 12) I would hard-code the default values instead of keeping them in a separate external file.

That way, current users would not have to worry about a new file and power users such as yourself could use a configuration file to produce this different output.

[axelhahn]

Ah, I did not read your 1st response carefully enough :-)
One question is where to place the config. On Linux I think that $HOME/.config/docblox2md.js ist OK. Maybe to simplyfy the access on different platforms it is easier to put it to $HOME. I will prepare some basic code. (I wrote javascript in web applications and did not work with node so far).

[vphantom]

IMHO it should simply be in the current working directory, which would typically be the root of whatever project the user's in. (This is how other JS tools like postcss behave.) If you try to load the file without any path specified (i.e. '.docblox2md.js', it should behave as is commonly expected.

[axelhahn]

a little update:

• cli writes a md file only on changes.
• docblox2md: add config (a hash) in docblox2md and try to find a config in one of the given places
  What do you think about the current branch?

[vphantom]

I like your improvements. 👍

I see you updated formatting a bit. I just realized this project didn't include my .prettierrc yet, so I added it moments ago. I realize the whole "tabs vs spaces" is a hot debate but it's the configuration I use in my other projects so I'd like to update docblox2md to use it as well. If you rebase your branch, your editor's Prettier support (if it's what you're using) should pick it up automatically. Otherwise I'll probably just wait until after the merge and apply the formatting then.

Is this your final version? If so I'll download/test it and merge by tomorrow so it can go out on NPM.

[axelhahn]

Yep, I would like to leave it for the moment. If you agree the list of the checked custom config files.
The custom config variable I renamed the variable to "config" and added a subkey "output" - because maybe it comes to your mind to configure something else. This custom configuration stuff is not documented yet.

My nodejs experience is close to zero - please run the checks regarding code formatting.

[vphantom]

What was the motivation behind commit cli: do not write file if there is no change? It might affect certain workflows if the target file is not modified or at least touched to reflect that it's up to date vs its source material. I don't think it's a big deal but I'd like to understand it better.

[axelhahn]

In my project documentations I describe installation, usage and "not all" markdowns contain a block for replacements for docblox2md. If I want to be lazy and execute it with *.md to loop over all files it is not needed to write files that
a) do not contain a docblox section anywhere and
b) a md file with replacements which is still up to date also does not need a new timestamp.

I think it is an expected behaviour that if there is no change in a file then do not overwrite it with the former content.
If you don't agree I still can run something like this to skip non docblox markdown files
docblox2md -v $( grep -l [DOCBLOX-MARKER] )

[vphantom]

I see, yes. I had not thought about the *.md scenario and I agree that it is useful to skip those which are not relevant. Perhaps we could skip files without docblox sections instead of files which don't need modifying. As a bonus, that skipping could be earlier in the process (as soon as we know there are no blocks).

The use case I was thinking of was a build tool like GNU Make with explicit rules (i.e. something.md depending on something.js), where docblox2md would be run every time the rule is hit as long as the source file is more recent than the target. It's a minor point but I was wondering if we should try to avoid that situation.

[axelhahn]

like in filterDocument() ... it needs a small method similiar to var sections = doc.split(re.mdSplit); that just returns the count (length). I try in in the next few time.

[axelhahn]

I added hasPlaceholder() that returns boolean for "is there a placeholder or not?" Only markdowns without placeholder will be skipped now.

[vphantom]

Thank you. I think that takes care of every use case. I'll merge this soon. 😃