I think we'll need the ability both to document the interface in a particular charm, and to link to other charms interface docs from inside such documentation.
So a charm which implements another charms interface exactly (perhaps by importing code from that charm's codebase) could say "this is properly documented over <here>". Another charm could say "we aspire to work with the interface as defined <here> but here are some gotchas associated with our implementation". Mark On 04/10/13 09:35, Nick Veitch wrote: > The issue which I think kicked this off is that charm authors wishing > to build against the interfaces offered by a specific charm have > nowhere to go to find out e.g. what is exposed by relation_set for a > particular interface, or what those values relate to. > > We can include best practice guidelines for common interfaces (http > say) in the main documentation, but for specific stuff I currently see > nowhere, other than trawling through individual hook code, where that > information can be obtained (and even then it often isn't explained). > It has to go with the charm itself *somewhere*, doesn't it? > > > > > > > On Thu, Oct 3, 2013 at 7:21 PM, Gary Poster <[email protected] > <mailto:[email protected]>> wrote: > > On 10/03/2013 01:50 PM, Mark Shuttleworth wrote: > > > > Are we talking about documentation of the config (lightweight) or > > documentation of the whole interface, for development purposes? > > Ah, thanks. I was obviously speaking of the former, but after > re-reading the start of the thread, it seems Jorge was discussing > documentation of the whole interface. > > I think that whole-interface documentation should be outside of a > charm, > because mutiple charms can fulfill a given interface. In that case, > doing what Jorge seemed to be suggesting initially--putting it in the > primary Juju docs--seems the right way within our current doc > world. We > don't use YAML for that, so Nate's point is good. > > Gary > > > > > > > On 01/10/13 14:40, Gary Poster wrote: > >> On 09/30/2013 09:47 AM, Nate Finch wrote: > >>> I would recommend not making documentation an attribute in > yaml. That > >>> puts strong pressure on writers to make their documentation > extremely > >>> short. No one will want to type out a full page of > documentation into a > >>> yaml attribute. Far better to make the documentation into a > separate > >>> file, to emphasize that you can write as much as you want (and > more > >>> documentation is almost always better). > >> I'm not sure I agree with you here, but AFAIK the discussion is > moot > >> unless we want to rejigger most or all of our charms. The config > >> documentation is already in the YAML. > >> > >> Every config element in config.yaml has a description. A > majority of > >> them have multi-line descriptions, which describe how to use them. > >> Here's one of bunches of examples. > >> > >> nagios_context: > >> description: | > >> Used by the nrpe-external-master subordinate charm. > >> A string that will be prepended to instance name to set > the host name > >> in nagios. So for instance the hostname would be > something like: > >> juju-myservice-0 > >> If you are running multiple environments with the same > services in > >> them > >> this allows you to differentiate between them. > >> type: string > >> default: "juju" > >> > >> Gary > >> > >>> > >>> On Mon, Sep 30, 2013 at 9:16 AM, Richard Harding > >>> <[email protected] > <mailto:[email protected]> > <mailto:[email protected] > <mailto:[email protected]>>> wrote: > >>> > >>> Yes, we can do this. We currently support doing markdown > rendering of a > >>> charm's readme in JS. Jorge, how are we looking to have > users document > >>> their interfaces? As a description attribute in the yaml? > Could that be > >>> easy to write out as markdown? > >>> > >>> On Mon, 30 Sep 2013, Mark Shuttleworth wrote: > >>> > >>> > > >>> > Are there good markdown renderers in JS? Should we aim > for interface > >>> > documentation in MD? > >>> > > >>> > On 30/09/13 12:32, Richard Harding wrote: > >>> > > On Wed, 25 Sep 2013, Luca Paulina wrote: > >>> > > > >>> > >> On Wed, Sep 25, 2013 at 3:06 PM, Jorge O. Castro > >>> <[email protected] <mailto:[email protected]> > <mailto:[email protected] <mailto:[email protected]>>> wrote: > >>> > >> > >>> > >>> Hi everyone, > >>> > >>> > >>> > >>> I'd like to revise the charm quality stuff a bit, > mostly the > >>> ~charmers > >>> > >>> have captured that we would like to encourage folks to > >>> document the > >>> > >>> interfaces in their charms and I'd like to add that > as a charm > >>> quality > >>> > >>> bullet item. > >>> > >>> > >>> > >>> In the past that just meant getting a +1 from some > charmers and > >>> > >>> editing the docs, but now that we have a GUI I want > to make > >>> sure we > >>> > >>> don't add things to the guidelines and not sync up > with the > >>> GUI and > >>> > >>> design teams, so what would be the best way for me > to drive that > >>> > >>> forward? > >>> > >> Thanks for the email Jorge, maybe we can find sometime to > >>> discuss it > >>> > >> tomorrow over a hangout. There is a need to revise > the copy of > >>> the intro > >>> > >> paragraph as well, we should discuss that at the same > time. > >>> > >> > >>> > >> Thanks, > >>> > >> > >>> > >> Luca > >>> > > Did this happen? To answer the first, question, a bit on > >>> charmworld to add > >>> > > the new QA item with the text and section to place it > in will > >>> allow us to > >>> > > add it to the QA process. The Gui will then pick it up and > >>> adjust scores > >>> > > accordingly. > >>> > > > >>> > > -- > >>> > > > >>> > > Rick Harding > >>> > > > >>> > > Cloud Engineering > >>> > > https://launchpad.net/~rharding > <https://launchpad.net/%7Erharding> > >>> > > @mitechie > >>> > > > >>> > > >>> > >>> -- > >>> > >>> Rick Harding > >>> > >>> Cloud Engineering > >>> https://launchpad.net/~rharding > <https://launchpad.net/%7Erharding> > >>> @mitechie > >>> > >>> -- > >>> Juju mailing list > >>> [email protected] <mailto:[email protected]> > <mailto:[email protected] <mailto:[email protected]>> > >>> Modify settings or unsubscribe at: > >>> https://lists.ubuntu.com/mailman/listinfo/juju > >>> > >>> > >>> > >>> > >> > > > > > -- > Juju mailing list > [email protected] <mailto:[email protected]> > Modify settings or unsubscribe at: > https://lists.ubuntu.com/mailman/listinfo/juju > >
-- Juju mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju
