search

bioperl / bioperl.github.io

The BioPerl Web site: http://bioperl.org
14 stars 9 forks source link

Create markdown README out of pod for all modules #2

Closed majensen closed 8 years ago

majensen commented 8 years ago

As I'm going through HOWTOs, I see many links to modules. What if we (could be 'I') create a README.md (using https://metacpan.org/pod/Pod::Markdown) out of all the module pod that will live in the module's directory. These can be linked to from the HOWTOs and elsewhere. @pcantalupo @hyphaltip @cjfields @bosborne

bosborne commented 8 years ago

Mark,

What I’ve been doing is something like this:

[Bio::Biblio](http://search.cpan.org/search?query= Bio::Biblio)

Which doesn’t get you straight to the page on CPAN, but close to it. That said, I think your suggestion is a good one.

BIO

On Dec 2, 2015, at 10:04 AM, Mark Jensen notifications@github.com wrote:

As I'm going through HOWTOs, I see many links to modules. What if we (could be 'I') create a README.md (using https://metacpan.org/pod/Pod::Markdown https://metacpan.org/pod/Pod::Markdown) out of all the module pod that will live in the module's directory. These can be linked to from the HOWTOs and elsewhere. @pcantalupo https://github.com/pcantalupo @hyphaltip https://github.com/hyphaltip @cjfields https://github.com/cjfields @bosborne https://github.com/bosborne — Reply to this email directly or view it on GitHub https://github.com/bioperl/bioperl.github.io/issues/2.

carandraug commented 8 years ago

@bosborne said:

What I’ve been doing is something like this: [Bio::Biblio](http://search.cpan.org/search?query= Bio::Biblio) Which doesn’t get you straight to the page on CPAN, but close to it. That said, I think your suggestion is a good one.

Or you can just have:

  `[Bio::Biblio](https://metacpan.org/release/Bio-Biblio)`

which list all modules, documentation, and NEWS file from the latest version of that distribution. Or to a specific module, MetaCPAN does not use the releaser and distribution name on the URL so you can have:

  `[Bio::Biblio](https://metacpan.org/pod/Bio::Biblio)`
majensen commented 8 years ago

@bosborne that makes sense; I think @carandraug 's use of metacpan is a good way to go.

There may be other reasons even so to create md version of the pod in the repos -- e.g., people going to the repo on github could see the pod directly and nicely formatted, rather than having to wade through the raw code. Also, maybe the version in CPAN isn't really the one someone wants to refer to.

Maybe I'll fool with a bioperl-live branch and we can see how it looks-

carandraug commented 8 years ago

@majensen said:

There may be other reasons even so to create md version of the pod in the repos -- e.g., people going to the repo on github could see the pod directly and nicely formatted, rather than having to wade through the raw code.

I'd argue that people going though the repo on github ought to be developers and therefore should be able to read the POD used to generate the documentation.

Also, maybe the version in CPAN isn't really the one someone wants to refer to.

On metacpan, the links I mentioned aboved, there's a dropdown box on the right side to select the version. Of course, it defaults to the latest.

Also, committing such files goes against the principle of not committing the build results (the md version would be a build target with the pod being the source). That's one more thing to keep in sync. The purpose of metacpan is search for modules and see their documentation. Why not just use it?

majensen commented 8 years ago

Hmm. Well, ok, we could build the markdown and organize it on bioperl.github.io. (Why would there be L<> in pod if it wasn't meant to be rendered?) The last version on CPAN as we all know is 1.000000000069xxxxxx, and people coming to github rather than metacpan may be those who want to see the live docs. But it really isn't a big deal. Especially for the old howtos, I'll go with metacpan.