The Puppet Labs Issue Tracker has Moved: https://tickets.puppetlabs.com

Feature #15528

High Level Feature #15403: Automatically produce & display useful documentation about a module

Show module's README.md file as the module description

Added by Dominic Cleal about 2 years ago. Updated about 1 year ago.

Status:ClosedStart date:07/15/2012
Priority:NormalDue date:
Assignee:Melinda Campbell% Done:

0%

Category:documentationSpent time:-
Target version:Better documentation and metadata
Keywords:readme, docs Affected URL:
Branch:

We've Moved!

Ticket tracking is now hosted in JIRA: https://tickets.puppetlabs.com

This issue is currently not available for export. If you are experiencing the issue described below, please file a new ticket in JIRA. Once a new ticket has been created, please add a link to it that points back to this Redmine ticket.


Description

The module description used on the Forge could be optionally populated from a README{,.md,.markdown} file stored in the module itself. For those modules that already maintain a README as part of the module, this will prevent the text on the Forge from becoming stale.

A radio button on the module edit page would perhaps allow the user to select between the two options – edit on the site as today, or enter/select a filename from within the module.

(This may be a subtask of #15403)

History

#1 Updated by Ryan Coleman about 2 years ago

  • Status changed from Unreviewed to Accepted

Thanks Dominic!

Just to recap:
Users should be able to make their README the modules documentation or choose to write something from scratch. Users should be able to modify this choice at any time.

#2 Updated by Ryan Coleman about 2 years ago

  • Parent task set to #15403

#3 Updated by Ryan Coleman about 2 years ago

  • Assignee set to Melinda Campbell

A supporting user story:

As a module author

I want the forge to use documentation already present in my content

So that I don't have to repeat myself

I’m keen on Dominic’s suggestion to offer this during publish and to always allow a user to split off from the automatically scraped description/README and specify something just for the Forge.

Assigning to Melinda to kick off the UX conversation.

#4 Updated by Ryan Coleman almost 2 years ago

  • Assignee deleted (Melinda Campbell)
  • Target version set to Better documentation and metadata
  • Keywords set to readme, docs

This is accepted into our next batch of work regarding documentation and metadata, which is scheduled next.

#5 Updated by Melinda Campbell almost 2 years ago

  • Assignee set to Melinda Campbell

#6 Updated by Melinda Campbell almost 2 years ago

We should add a line to the publishing modules doc (http://docs.puppetlabs.com/puppet/2.7/reference/modules_publishing.html) explaining that when you upload a module, the module page will automatically display your README file.

#7 Updated by Ryan Coleman about 1 year ago

  • Status changed from Accepted to Closed

This shipped a while back.

Also available in: Atom PDF