Ignore docs/ directory #373
Conversation
|
FWIW, checked with @HAIL9000 and she said that the generated docs shouldn't be committed. however, there could be modules that have a doc dir. Currently, puppet-r10k seems to be the only modulesynced module that has a doc/ directory. |
|
Hi, |
|
@bastelfreak generated files do not belong in git. It goes out of date or you get very ugly commits that change irrelevant files. It's also a great source of merge conflicts. As for an idea to publish them: aren't github pages served from the gh-pages branch? I'd be fine with some hooks that autogenerate that branch but adding them and referring to http://www.puppetmodule.info/ sounds like a better idea. |
|
@bastelfreak It's |
|
what about a travis hook thingy that regenerates and pushes the docs after each merge? I really love the work @domcleal put into http://www.puppetmodule.info/ and I would like to see more of our modules documented there - but also keep the docs in the module (which makes them automatically accessible via our website) |
|
You could add a badge like we do on https://github.com/Katello/puppet-pulp (and should do for other modules). |
|
I'm against merging this. I think it is really nice to have all documentation for the modules easily available like:
I would like to have this official and link to those docs at our landing page. IMO instead of merging this we should improve the generation of those docs, maybe via a github hook at each PR or via travis. And in addition publish to http://www.puppetmodule.info/ |
|
@bastelfreak I don't see how they have to be in the git repo to be available on those URLs. |
|
Do you have any other idea to place them there? |
|
FWIW, re: http://www.puppetmodule.info/, I don't think we have to publish, it seems to magically pull YARD docs, whether generated by strings or not. And I think once added there once, it should check that the docs are up to date when someone requests them? What about the idea of using the gh-pages branch? Presumably, Forge could display strings docs inline at some point as well. |
On some local filesystem? I consider them caches and you don't commit caches to git. |
|
Can travis commit to a github-pages branch or repo? This is what we're doing with internal module docs at work (though with Gitlab), we have a CI job that builds and deploys the docs to a URL.... no gh-pages branch, no docs dir in the repo |
|
@dhollinger that's what I suggested in #373 (comment) so that'd work for me. |
|
The gh-pages approach sounds like a very reasonable approach to me, if it will work. |
|
every github repo has some option to set what to serve as github pages. an option is to have docs/ which we have choosen back then. another option is to have a dedicated branch - gh-pages IMHO puppetmodule.info IMHO compiles the pages itself with puppet strings. |
|
I think a separate branch would be preferable to docs subdir, for the reasons mentioned by others, mostly dealing with the history, diffs between tags, etc. If we tag in the gh-pages branch with each release, presumably it would be possible to view docs for each version of a release still, right? |
https://github.com/domcleal/puppetmodule.info does use puppet strings indeed. |
|
FWIW, having the docs folder in the repository lowers the cost of entry to using the module. Puppet strings being all new and shiny creates a perceived barrier for adoption if you have to generate them on your own. Also, module development work happens offline or with an air gap. The gh-pages URLs don't help all that much. Same thing happens when there is a new puppet release: I'm downloading the documentation tarball from Puppet for use on my laptop. |
|
Personally, if I'm not viewing online, I'm more likely to just read the human readable docs in the manifest vs. opening up local html files. But this is one reason I'd like to see the README generated from strings long-term (and a way to select what info goes into the README). Of the options suggested so far in this thread, though, I like the gh-pages branch option the best. |
|
I got some positive feedback about the docs in our repos during puppetconf. IMO they should stay in docs/ and we automate their generation. |
|
Since we're going to leave them in docs, does someone want to submit a PR for the actual plumbing to make this work automagically? |
|
@bastelfreak could we ship docs in releases, but not in git versions. Would that be sufficient? |
|
they then are not available as github pages.
…
@bastelfreak could we ship docs in releases, but not in git versions.
Would that be sufficient?
|
|
@ekohl I would prefer it to have them in the repos and automatically update them regulary with any automation |
|
We can still solve that via gh-pages. I'd really like to avoid autocommitting things to master and if you don't, they go out of sync. It creates a lot of noise and I'm already ignoring many updates from modules because it's too much. My biggest worry is that I'll need to spend too much time keeping up and decide not to keep up at all resulting in reduced involvement. |
|
I don't want any more noise as well. There are multiple bots out there to automate github interaction. It should be possible to automate the generation of the docs. |
|
I still feel strongly that we shouldn't autocommit generated to master, especially if we don't have to. It blows up the repository size more than needed and clutters the git log. As a user I often look at git logs to see how things changed. |
|
Closing this PR, but created #397 to deal with discussion and / or tracking some mechanism to auto-push docs. |
Not sure if (m)any modules have a doc directory; also not sure whether we'd check in docs generated by
puppet strings, or whether we want to ignore these. If we do want to ignore them, this PR will accomplish that.