Add support for --include-template #168

Open
tobiastom opened this Issue Jan 7, 2012 · 3 comments

Comments

Projects
None yet
2 participants
@tobiastom

This switch would work exactly like the --include switch, with the exception that it will process all templates (without the required "-template" suffix).

With this I would include guides written in markdown into the documentation, without the requirement to rename them all.

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Jan 7, 2012

Owner

Not sure I understand your point, appledoc does process all templates in --include paths (in lack of better term - template file is actually normal markdown file, except it has suffix -template). appledoc then strips -template suffix when generating output documentation, so you can link to these files simply through their "inteded" file name (for example to link to document-template.markdown, simply write document anywhere).

By using special filename, processing can be faster as only these special files can be processed. Although it would be possible using special --include-template switch and treat every file in the path as template, I don't see real benefit doing this (besides perhaps shorter file names)?

Also see static documents documentation for more info on this topic.

Owner

tomaz commented Jan 7, 2012

Not sure I understand your point, appledoc does process all templates in --include paths (in lack of better term - template file is actually normal markdown file, except it has suffix -template). appledoc then strips -template suffix when generating output documentation, so you can link to these files simply through their "inteded" file name (for example to link to document-template.markdown, simply write document anywhere).

By using special filename, processing can be faster as only these special files can be processed. Although it would be possible using special --include-template switch and treat every file in the path as template, I don't see real benefit doing this (besides perhaps shorter file names)?

Also see static documents documentation for more info on this topic.

@tobiastom

This comment has been minimized.

Show comment Hide comment
@tobiastom

tobiastom Jan 8, 2012

For example I have a Documentation/Guides directory, where each file is markdown based. They are already inside the repository.

With your "-template" suffix I would need to rename each and every file, and even worse: each file inside that directory would be required to have this -template suffix. As all files inside this directory should be processed anyway, having this name scheme applied seems to be very strange.

Having this additional --include-template switch, we would keep your existing idea about being as effective as possible, and even cover edge cases like mine to generate files from a complete markdown-based directory.

For example I have a Documentation/Guides directory, where each file is markdown based. They are already inside the repository.

With your "-template" suffix I would need to rename each and every file, and even worse: each file inside that directory would be required to have this -template suffix. As all files inside this directory should be processed anyway, having this name scheme applied seems to be very strange.

Having this additional --include-template switch, we would keep your existing idea about being as effective as possible, and even cover edge cases like mine to generate files from a complete markdown-based directory.

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Jan 8, 2012

Owner

It would make sense for cases like this.

Owner

tomaz commented Jan 8, 2012

It would make sense for cases like this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment