search

jesselang / dox

Publish markdown to Confluence as HTML
MIT License
23 stars 5 forks source link

Add support for custom root page content #6

Closed mitchell-then closed 5 years ago

mitchell-then commented 5 years ago
mitchell-then commented 5 years ago

This pull request contains quite a few changes, and a medium sized rewrite of how publishing is done. I considered implementing some type of page dependency management, but ultimately decided against it as the only dependent pages right now are between the root and child pages.

Since this is a large change of how publishing works, I'm looking for feedback on how I'm trying to do things. I'm not completely convinced that my implementation of the dox header is in good shape either.

mitchell-then commented 5 years ago

One problem yet to be solved: remove requirement of having a title defined in the dox config file when using a source as a root page.

jesselang commented 5 years ago

Hey Mitch. I like the idea of being able to specify some content for the root page. But specifying it in the page seems like it could be prone to problems. The source options introduced so far have affected only that source (i.e. ignore excludes the source from being published, omit-notice omits a generation notice only that source, etc.), but the root page really affects all sources, as all sources become children of that root page. Also, there can logically only be one root page, which also brings up a case where a user has added the directive to multiple pages in the repo, which should not be allowed.

One possible direction to take could be to use convention over configuration. By specifying a conventional source location used by dox, no configuration would be necessary, because the source is either present or isn't, and only one source can be at that location. How do you think that would fit into your use cases?

mitchell-then commented 5 years ago

Hey Mitch. I like the idea of being able to specify some content for the root page. But specifying it in the page seems like it could be prone to problems. The source options introduced so far have affected only that source (i.e. ignore excludes the source from being published, omit-notice omits a generation notice only that source, etc.), but the root page really affects all sources, as all sources become children of that root page. Also, there can logically only be one root page, which also brings up a case where a user has added the directive to multiple pages in the repo, which should not be allowed.

One possible direction to take could be to use convention over configuration. By specifying a conventional source location used by dox, no configuration would be necessary, because the source is either present or isn't, and only one source can be at that location. How do you think that would fit into your use cases?

I agree, if we look for a file at a predetermined location and use that as the root page, it would solve some problems.

I think we can safely rule out using the README.md file at the root of the repo for this purpose as it would be present in many repos (custom root page for all repos?), and I don't think it would make sense to use the contents of a README as a root page in all cases.

So that would mean creating our own convention, such as dox_root.md at the root of the repo. I believe this would work well in many cases. A possible problem is that I may want all my dox source files to be in a single location, like docs/ (or maybe dox/) in the repo. But I think that would be a non-issue as the root page is somewhat of an exception.

I'll go ahead and start implementing this idea. What are your thoughts on the name of the file? dox_root.md, DOX_ROOT.md, doxRoot.md?

jesselang commented 5 years ago

I think we can safely rule out using the README.md file at the root of the repo for this purpose as it would be present in many repos (custom root page for all repos?), and I don't think it would make sense to use the contents of a README as a root page in all cases.

Agreed.

So that would mean creating our own convention, such as dox_root.md at the root of the repo. I believe this would work well in many cases. A possible problem is that I may want all my dox source files to be in a single location, like docs/ (or maybe dox/) in the repo. But I think that would be a non-issue as the root page is somewhat of an exception.

That's certainly a realistic use case. Could dox check the root of the repo first, then fall back to a file matching the convention anywhere in the repo?

I'll go ahead and start implementing this idea. What are your thoughts on the name of the file? dox_root.md, DOX_ROOT.md, doxRoot.md?

I'm wondering if we could simply go with ROOT.md, which seems descriptive, but not specific to dox, and maybe that's OK. I haven't seen a lot of ROOT.md files in repos.

mitchell-then commented 5 years ago

Squashed commits, and have tested with some use cases. This pull request should be in a good state to merge.