Announcing www.chefdoc.info - A service for serving cookbook documentation

Chef Infra (archive)
1

TL;DR: Announcing http://www.chefdoc.info, a chef cookbook documentation service modeled after the infamous rubydoc.info.

I thought chef cookbooks need a better documentation style than “write a README”, so I created the basis for one. I took yard-chef and rubydoc.info and after some hassle http://www.chefdoc.info was born. This is an early release, so don’t expect too much, but still, I hope you like it. And of course, it’s open source: https://github.com/chefdoc. The production service is running in a Docker container which is available at https://hub.docker.com/u/chefdoc/.

The most important aspect behind all this for me was to start with a very limited, and basic functionality and create documentation guidelines with the community. So apart from code contributions I also need input if a project like this makes sense at all and how it should progress.

Planned features:

  • Support for private supermarkets and chef servers, so you can deploy chefdoc in your own infrastructure and have it document your cookbooks.
  • Support for Definitions, LWRPs and custom resources.
  • Cross linking within a cookbook, eg. link node attributes to where they are defined.
  • Showing a dependency graph in some way.
  • Display available metadata.
  • Add cookbooks file and templates to docs and crosslink them inside the recipe source.
  • If you have CSS/HTML/JavaScript skills and want to contribute to make chefdoc look nicer I would be very glad. :wink:

Notes about the service:

  • I am currently hosting on sloppy.io, but they don’t offer sharing volumes between Docker containers which means I can not cache anything. So I will move to some other hosting service (probably Linode) in the future which should offer a major performance boost.
  • Some cookbooks seem to not work at all. If you find one, please add it to the issue tracker: https://github.com/chefdoc/chefdoc.info/issues/1

Any kind of feedback, especially in form of pull requests is welcome.

2 Likes
2

Looks good. I would really like to see it in my private network. Sometimes browsing through cookbooks is so tedious.

3

Looks promising, thanks for sharing this with the community. Support for running on internal infrastructure for cases where cookbooks can’t be publicly released would be nice to see.

4

Supporting private infrastructure is definitely on my roadmap. If you want to look at some code [1] it would actually be quite simple to support additional endpoints. What would be your use case? What do you use, a Private Supermaket, Chef Server or something else?

[1] https://github.com/chefdoc/chefdoc.info/blob/master/lib/extensions.rb#L44

5

We don’t use a private supermarket, just a git repo per cookbook and the internal chef server.

6

Well, some kind of git integration might come in the future but that definitely is not very high on my list. Integration with any chef server v 2.6 (this version includes the universe berks endpoint) or higher will probably come within the next few weeks.
Of course I would also be very happy about a pull request with this feature. :wink: If you got some time I can point you to the steps required.

7

@sme Using a chef_server as cookbook backend is now supported, als long as the chef server version is at least 12.4. You can find some getting started docs at https://github.com/chefdoc/chefdoc.info/wiki/Getting-started

1 Like
8

Nice work, will give this a look internally. Thanks again for providing the resource to the community!

9

@joerg.herzinger Useless post for the thread, but thanks a lot for the efforts, I did initiate this path with yard internally a year ago, but without a central acces it did die a few weeks later.

So thanks for the hard work, I’ll try to free some time for a git* integration in the next weeks.

10

My version was not so fancy :slight_smile:

Hope will find some time to merge some my features to yours :slight_smile: