Move doc/ to resources/

[coke]

History - we originally had docs in lib/ and took advantage of this during the installs so that p6doc would be able to find the installed libs. At some point, I moved this to doc/ so that we could keep separate the modules used to build the site or run p6doc. We then created a Build.pm to copy those files from doc/ into the installed lib/ dir to mimic the original functionality.

This worked, but at some point, trying to create the files this way during install caused permission issues as the install is going to the wrong directory (and the user running the install may not have permissions in that folder)

However, since then (2014!), a resources/ mechanism has been introduced. Files in resources/ can be installed and then retrieved via %?RESOURCES.

• Move any top level doc/* files into resources/*
• Update tests, scripts, and build to track new directory
• Add all pod6 files expected to be readable after install to the META6.json file.
• Add a test (t/) to insure we report on any missing or extra files (so we can track add/remove/rename)
• Remove custom Build.pm6

[coke]

This task should resolve #2896 (Broken install) - may require slightly more work to make p6doc 100%

[JJ]

It would solve p6doc; it would probably break everything else. Main problem is that current CUR precompilation is not compatible with Documentable's cache. It would make a lot of sense if Documentable's cache was compatible with CUR, which it should really be.
Also, #2896 is solved with the new p6doc... which, alas, we haven't deployed yet. So I see this as something at the tail end of the 2.0 roadmap #2983. What do you think?

[coke]

What is "the new p6doc" ?

[coke]

Also, bin/p6doc doesn't use Documentable. (I'm referring to the script, not the overall repo)

[JJ]

The new p6doc does. Please check the roadmap, it's a project that was finished last summer.

[coke]

Can you point me at the Roadmap? I don't see one by that name in the wiki or the files in the repo.

[JJ]

I already did in my first reply, it's issue #2983

[coke]

So, whichever of the 4 repos described in #2983 is going to install the pod files for next-gen p6doc to read needs this change to correctly install the files.

Is the plan that this repo will do that install and other repos will read them? This is what I would expect, then I would have ng-p6doc depend on this module (rather than using a git sub-module or something similar)

[JJ]

So, whichever of the 4 repos described in #2983 is going to install the pod files for next-gen p6doc to read needs this change to correctly install the files.

Is the plan that this repo will do that install and other repos will read them? This is what I would expect, then I would have ng-p6doc depend on this module (rather than using a git sub-module or something similar)

It already depends on documentable, since it shares some common functionality. If we eventually decide to install Raku/doc in the RESOURCES, well, we'll add it as a dependency, but for the time being what we need is to have a working documentable cache initialized. And yes, that will go to the documentation of p6doc when it's eventually deployed.

[coke]

Where can I read up on the Documentable cache so I can find out what problem it's trying to solve, and why it's in conflict with the resources/ fix?

In the meantime, if you're not intending for users to install the docs and bin/p6doc from this repo, we should remove the Build.pm, and bin/p6doc - Leaving the install & tools in a broken state (esp. when fixes are occurring in a different repo) is bad for the users. (we could leave bin/p6doc if it's partially working, but I know it's broken for some cases)

[JJ]

Where can I read up on the Documentable cache so I can find out what problem it's trying to solve, and why it's in conflict with the resource/ fix?

Of course, in https://github.com/Raku/Documentable

It's not in conflict. It simply uses a different mechanism to index precompiled documents, due to lack of documentation of the CUR API. Anyway, the doc precompilation needs to go a bit further than that, since it also pre-indexes and does a host of other stuff.
Baseline is: it would be nice to really understand how CUR works and make it work for us here. That was pretty much laid out in this issue. Please note that this is totally independent of deploying the new p6doc. Current-new one works with current documentable.

In the meantime, if you're not intending for users to install the docs and bin/p6doc from this repo, we should remove the Build.pm, and bin/p6doc - Leaving the install & tools in a broken state (esp. when fixes are occurring in a different repo) is bad for the users. (we could leave bin/p6doc if it's partially working, but I know it's broken for some cases)

I recently merged a PR with some fixes: #3196. I'd rather have something partially working than nothing, although, TBH, p6doc usage might be so close to zero that it's totally undistinguishable from it, which might explain why there are no more complaints about it not working. Anyway, it's something that we should offer and we'll do that, as soon as we get around to it (but there are other issues in front of them).

[tbrowder]

I whole-hearted support the efforts of all to make the resources available without the user having to do a lot of magic he shouldn't have to worry about. I did file an issue with Rakudo about access to %?RESOURCES but ran into the CUR roadblock pointed out by @ugexe (issue #3821 which I closed after Nick's explanation), but he did show a hackery solution for the existing CUR.

[JJ]

This issue is not rejected, it's admitted and part of the roadmap. However, it needs some way to go... The first thing would be to make this an only-docs repo, and spinning off all tooling for generating webpages or whatever. Which will be done eventually, but as said, some way to go...

[coke]

Since we don't install this repository anymore (for some time), my request to align the folder structure with the install structure doesn't matter. No need for the change unless we go back an install model.