Hi, I want to create a system that will show documentation about Raku
Modules that I have installed.
There does not seem to be a Documentation standard, or best practice,
for Raku modules.
Hence the following post.
In the Modules documentation in the Language section of the Raku
documentation, there is a single mention of README.md, but only that it
is needed by github. There is no indication about what should be in
README.md
As a user of Raku, this does not matter much to me in practice, as when
I need to understand something, I look at the code on the repository.
But it can be a hassle going to Modules.raku.org, finding the module,
going to the repo, finding where the information is, etc. I do NOT try
and find the information that has been installed by zef because the
location names are not human friendly. I understand the reasoning there,
and do not suggest any change. But it is not easy to find documentation
on locally installed modules, even though the information is there.
Even the "zef --open browse <entity> source" command opens a browser to
the internet repo, not to the local installation. There is no "zef
documentation entity" or "zef README entity" command. I am NOT
complaining about zef because the problem is not with zef, per se, but
with the absence of a documentation standard (I think).
I wanted to incorporate a page with documentation of modules in the
Collection-Raku-Documentation system I have just released.
But I do not see how to do this.
Most Raku modules have a README.md, which is required because of github
requirements. Although the README's of some modules leave a great deal
to be desired.
Many modules have extensive POD6 inside the main 'lib/module.pm6' file
(where 'module' obviously is a placeholder for this email).
There is an issue on the GTK::Simple repo, which I am now the maintainer
of, for more documentation. Actually, I learnt how to use GTK::Simple by
looking at the examples in the repo, which have lots of explanation. But
the README.md is appalling. However, an unanswered question is where
would I put a documentation file when I write it, so that it is useful
for users wanting to understand more.
In the modules I am now developing, I have a README.pod6 file, which I
convert to the README.md file for github using a GUI tool in
Raku::Extraction. The advantage of this is that the README.pod6 can have
links to other pod6 files.
My suggestion is that some formal decision is made about documentation
for Raku modules, that some documentation good practices are put
together and included in the Modules page. My suggestion is that
documentation should be in one of the following:
- the main module, defined (perhaps) as the pm6 file with the same name
as the Distribution name
- a README.pod6 in the root
- a POD6 file pointed to by META6.json, eg a META6.json key that looks
like: "documentation": "/lib/MyModule.pm6" or something.
