Raku has code for handling the installation of distributions through CompUnit::Repository::Installation. It handles the part of the installation process that involves copying the files into their final location, path normalization, precompilation, as well as providing an interface for querying what is installed. Unfortunately it does not yet handle anything related to documentation.
Currently there is no useful way of finding documentation for Raku distributions. There is a program called rakudoc
, but it is generally only useful for core documentation. This would allow developers to query for documentation similar to how they can query for module names.
Since there is not a general way of accessing documentation, documentation in Raku distributions has been nearly non-existent compared to those in the Perl community.
Solves at least half of Raku/problem-solving/issues/393
The issue seen at Raku/problem-solving#393 is about how installing Raku distributions involves installing files that have not been declared in the META6.json file. While that issue affects more than documentation files, the solution implemented by this grant would act as prior art for what needs to be done to e.g. declaratively install bin/ files from a distribution.
One example I can think of is related to the work being done on rakudoc renderers, particularly in regards to generating online html documenation a site like raku.land might use. These tools will be able to leverage the aforementioned META6.json updates.
-
A META6.json spec for defining documentation related data is created.
-
Updates to core Raku code that allow it to install, uninstall, and query-for documentation files as defined by the updated META6.json spec.
-
Docs for CompUnit::Repository::Installation and modules are updated to mention the above changes.
-
Examples are added (via the roast as spec tests) that show how to access documentation using core Raku functionality.
Note: Integration into rakudoc
is not intendended to be part of this. Such an integration will be little more than copying and pasting the aforementioned examples, but there is some other unrelated work that would need to be done as well (making it installable via zef and how the user interacts with the CLI in regards to e.g. api/version/auth and multiple matching namespaces).
We need to update the META6.json spec to allow declaring our documentation files simlar to how we declare our source files with provides
. Something like:
"provides-docs" : {
"Text::Foo" : "docs/Text/Foo.rakudoc",
"Text::Foo::DocInModule": "lib/Text/Foo/DocInModule.rakumod",
}
This will allow us to know where to look up the documentation for a given namespace, including know if the source is in a module or a stand alone documention file.
When installing a distribution Raku could then iterate through provides-docs
to install (and precompile) the given files. There is a bit of nuance involved in this part due to the way rakudo hashes files to be used in namespace look ups. Rakudo does something like $filename = sha1("Namespace::Being::Installed")
when installing modules which is also used when looking up namespaces, but that would be ambigious when we have something like:
"provides": {
"Namespace::Being::Installed": "lib/Namespace/Being/Installed.rakumod"
},
"provides-docs": {
"Namespace::Being::Installed": "docs/Namespace/Being/Installed.rakudoc"
}
The Raku logic for querying installed files could then be extended to also search documentation namespaces. This will involve adding a new method similar to the existing candidates method, or alternatively a new argument on the existing method. Again, this will be some nuance here involving the namespace normalization and file system location.
At last we can write the spec tests to show how these pieces are used. We'll want to ensure cases such as the ambigious namespace example above are covered.
I am Nick Logan, ugexe on github. I have been a co-author of the Raku module manager Zef, and a core developer of the Raku programming language for over 10 years. I am also a member of the Raku Steering Council.
$2500 USD
Because that is a fairly significant change in behavior for existing uses. Consumers of
candidates
can know it is querying for module names and nothing else. If it also searched documentation then existing uses might start returning a different result based on a piece of documentation an unrelated distribution contains. We want to avoid affect module name resolution.I don't follow. One method searchesI think I understand what you meant, and address this later on by mentioning searching without using a fully qualified name is always going to have problems like this.provides
, and one would searchprovides-docs
. It does not imply anything about distributions themselves. Similarly if you want to find distributions that has a specificbin/foo
file, you would use the existing (and unfortunately named).files(...)
method.At this point I get the impression you may be assuming every document namespace in the proposed
provides-docs
would have a correspondingprovides
entry, but I'm not sure that should be the case. For examplezef
might have a document namespacezef
despite the fact there is no module with that namespace (and hencecandidates
won't find it byzef
).Yes, but I kind of think that is to be expected. Querying for namespaces without the name/api/auth/version has always been a potential source of pain. Ultimately this won't be a high level tool for end users, but something used to build those high level tools. For example a tool like
rakudoc
could calldocument-candidates
first, then callcandidates
/resolve
to see if the document candidate matches the module candidate. If it does not match it could warn the user or author to be more specific.If you are querying for an exact namespace including name/api/auth/version then no. If you are not querying for an exact namespace then yes things might not do what you expect. The same problem exists for
candidates
and module names. The unfortunate solution is to always use the full long name.I mentioned how that can be achieved earlier by end user tools like
rakudoc
via a call todocument-candidates
andcandidates
. I'm not sure I follow why there should be any additional logic occurring when something isuse
d, and indeed I think we want to actively avoid adding any runtime penality to module loading just so the user can potentially query for documents. Maybe I'm misunderstanding this point though.It would be exactly like provides, except the file name the author lists would be for documentation files instead of module files. So yes, but note there is nothing automatic about this - the author will have to explicitly declare these similar to
provides
.Because it is not an
IO::Path
, it is anIO::Handle
. Technically you shouldn't assume that you can access the path of$source
and ideally you can just work with the source that gets slurped. This is because modules likeCompUnit::Repository::Github
can generate a distribution that isn't back by a file at all (rather a socket), and so something like$source.IO.e
shouldn't be expected to work. In reality you might need a file path... this can still technically be figured out from theIO::Handle
object but I'll leave that as an exercise to the read so as not to encourage that pattern.Additionally code (such as the aforementioned
CompUnit::Repository::Github
) can register other names at runtime. For exampleCompUnit::Repository::Github
would show agithub
name and a line likegithub#repo<Raku-PathTools>#branch<main>#/
Nothing is added to so a repository unless you explicitly install it.
-I.
type includes useCompUnit::Repository::FileSystem
(namefile
), see:So
-I.
in this case just puts a non-default repository to the front of the chain (and thus it will be queried first which affects resolution). Note that aCompUnit::Repository::FileSystem
only ever represents a single distribution unlikeCompUnit::Repository::Installation
which may or may not be an important distinction for you.