So here's my 2¢, which will probably be followed up with some actual
development of stuff (I do put my money where my mouth is… although it might
take me a while to save up to spend it ha). Some of the minor details could,
of course, easily be adjusted, so don't fixate too much on them.
Right now, it is true that many of us use README.md for github. Some people
write this one by hand (I'm guilty of it), others (lizmat, for instance)
generate this from their *.rakumod file.
We can do a lot more with POD6 than we can with MD (as POD6 encodes things more
semantically than MD), so we should encourage pushing towards using that, and
then using a script to generate the MD (or HTML, in the case of a website).
The following would be my rough proposal:
(1) Standard the function/meaning of reserved blocks (e.g. =TITLE vs =NAME,
when to use one or the other or how they should be different). Perhaps as
larger projects like Red or Intl document extensive/larger documents, we can
see what patterns might emerge and evaluate.
(2) Just as we have /t, /lib, and /bin as standard module folders, use /doc[s]
as a default space for documentation. For those that prefer not to use inline
documentation, their pod6 files would reside here (which could also be
identically-named rakumod files, esp. when wanting to have declarator pod
included). In any case, .md files could be autogenerated here for use on
github, or .html for elsewhere. README.md (or index.html, for webpages) could
be autogenerated for github based on 4b.
(3) Localized documentation in /docs/local/zzz-XX. The localized documentation
could be made from a skeleton/fully stubbed file rakumod file (for declarator
stuff) or from a standard pod6 file whose file names coincide with the docs (or
lib) versions. I'd be happy to do some of the work here, as I plan to localize
a fair bit of my documentation for certain modules.
(4) To help with the above, several new META6.json keys:
a. docs-lang for the language of inline documentation (en default).
b. docs-root for the module whose docs will serve as a front page (e.g.
README.md or as the first text on aggregator pages)
c. docs-ext for an outside link to documentation, which would be a fallback
to any other documentation and contrasted with a general website.
For 4c, these could be added to the support entry, as support->docs and
support->website, and the docs-lang/docs-root could be under a single entry
with two subkeys.
Anyways, lengthy 2¢ but there we go :-)
Matéu
> On Mar 2, 2021, at 08:25, Richard Hainsworth <rnhainswo...@gmail.com> wrote:
>
> 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.
>
>
>
