On 22.08.23 15:17, Paul Marquess wrote:
> Happened to notice that https://github.com/Dual-Life/Devel-PPPort
> <https://github.com/Dual-Life/Devel-PPPort> displays a markdown version
> of its POD when you navigate to it on GitHub. Digging a bit deeper I see
> that does that by strong a README.md file in the .github directory –
> somehow GitHub spots it and uses it for the module landing page. Quite a
> neat approach because the .github directory doesn’t end up in the CPAN
> bundle. Also means that the plain-vanilla text README isn’t touched.
>
> Before I jump in with both feet and replicate this, do we have any
> guidance on the general approach? Also is there any tooling to automate
> the process? (Not that it’s a big deal to create it).
The .github/README thing is documented at
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes. I quite like it.
Here's some ad-hoc tooling I made myself (probably not entirely
appropriate for core):
https://github.com/mauke/Function-Parameters Both README and .github/README.md are autogenerated from the main module
POD. This happens via a hook into the Makefile.PL/make process.
https://github.com/mauke/Function-Parameters/blob/main/Makefile.PL is
boilerplate that loads the module-specific ExtUtil::MakeMaker settings
from
https://github.com/mauke/Function-Parameters/blob/main/Makefile_PL_settings.plx and, in maintainer mode, runs the code in
https://github.com/mauke/Function-Parameters/blob/main/maint/eumm-fixup.pl. The latter adds rules to the generated Makefile that automatically
recreate README (on 'make dist') and .github/README.md (on 'make' in
general) using the scripts in
https://github.com/mauke/Function-Parameters/blob/main/maint/pod2readme.pl and
https://github.com/mauke/Function-Parameters/blob/main/maint/pod2markdown.pl. The latter is relatively straightforward Pod::Markdown, but with a few
tweaks:
- It processes "github-markdown" sections, so I can put something like
"=for github-markdown ![...](https://...)" in my POD and use it to
render custom badges, but only on Github.
- For L<Module> links, it normally links to metacpan.org. But if the
target is a L<perl...> page, I have it link to perldoc.perl.org instead,
because metacpan doesn't know about generated perldoc pages such as perlapi.
- It understands "=for highlighter language=foo" sections and uses
them for syntax highlighting (by rendering all following verbatim
paragraphs as "```foo ... ```" fenced code blocks).
- It works around a Markdown syntax issue with list items that start
with a code block.
(In comparison, pod2readme.pl is very simple: It takes a few selected
POD sections and renders them as plain text.)