Separate “undocumented.json” from “docs”?

[SDGGiesbrecht]

Right now, CI, validation, change tracking, etc. that use tools like diff or git diff need to go to extra work to explicitly ignore each undocumented.json (and the docset .tgz that contains one), because source_directory causes output differences unrelated to the source code.

Also, is it wise to print the user’s username and file structure without notifying them—particularly into documents they are likely to publish? Some might see that as a security risk.

What purpose does source_directory currently serve? Is there a more consistent, more secure way of achieving that purpose?

[pcantrell]

The original rationale was to make it easy for developers — and especially for developer tools — to open the offending file.

It's the same reason why compilers, linters, and other build tools often emit full paths, though granted they usually send those paths to the console and not a file.

[SDGGiesbrecht]

Yes, that makes sense.

Would it be reasonable to output undocumented.json separately from the docs folder, or at least stop producing duplicates inside the .docset and .tgz?

That would make it easier for those of us who want to prevent inadvertent publishing of undocumented.json.

[jpsim]

I'd vote for keeping it in the output directory (docs/ by default) but not copying them into the .docset and .tgz.

[SDGGiesbrecht]

I'd vote for keeping it in the output directory (docs/ by default) but not copying them into the .docset and .tgz.

May I try to implement this, or is more review required first?

[jpsim]

If you want to do this, go for it!

[SDGGiesbrecht]

This is now implemented on master.