Version 2.0 Roadmap

[JJ]

Since markdown can't be used in a milestone description, I'm moving it here

After Google Summer of code, there are a couple of projects related to documentation: @antoniogamiz's Perl6::Documentable and @noisegul 's next-generation p6doc. They have made a great work, but we need to to put them to good use.
This milestone will gather all tasks related to introducing them as perl core documentation tools. Roughly, this is the roadmap:

• Adopt these modules as part of the Raku organization, so that anyone can work on them (done: Documentable, rakudoc)

• Test them thoroughly so that they reproduce as much as possible the current behavior. These first two need not be in the same order.

• Publish Documentable in the ecosystem.

• Start using Documentable to generate documentation

• Create a Documentable container for CI and independent generation

• Create a deployment script that depends on it.

• Delete all functionality from the repository that has been superseded by documentable.

• Modify utilities that depend on Pod parsing, such as Pod::To::OneBigPage

• Spin off web generation tools.

• Incorporate Documentable into Travis test

• Make the rest of the tools depend on Documentable, tests and so on.

• Move Documentable up the tool chain so that it gets used by Pod::To::OneBigPage and Pod::To::HTML. Or at least make them aware of the existence of the cache.

• Move all web assets and tools to a different repository.

• Move all Raku/doc tools to a different repository.

Eventually, the objective is to have 4 different repositories where there's now just one:

1. Raku/doc will contain just the documentation and tests related to it.

2. Raku/Documentable will contain the documentable script and modules.

3. Raku/doc-web will contain the assets and business logic to generate the static web pages and deploy it to the web.

4. Raku/rakudoc will contain the command-line interface to the documentation.

There are no actual modules that depend on the documentation, so we don't really foresee any breaking changes; however, since it's included in Rakudo Star, some bumpy road is expected. Please use this milestone to create issues that are related to this specific change.

[coke]

From #2998 - please add Documentable as a dependency for the project in META6.json, since it is now a requirement for the build. (Can be removed if we get to a point where the build is being initiated from inside a different repo)

[tbrowder]

It seems the steps out of order: the current build process has been removed from the doc repo before we have a working v2. Consequently, the current doc website is badly rendered, e.g., the general references section is missing.

[JJ]

@coke as indicated somewhere else, this repo is going to contain eventually only tools for checking documentation itself. Even needed static files will be moved elsewhere eventually.
@tbrowder we were testing documentable for a week in the stage server before deleting htmlify.p6. As a matter of fact, current https://docs.perl6.org has been generated using documentable. We checked that the new documentation generated all URLs. There might be some section missing somewhere, and I'll check this just in case. Please report if you find anything else missing.

[JJ]

@tbrowder I see what you mean now, it was reported also in Raku/doc-website#114. We'll try to fix that. Please keep reporting whatever you find.

[hankache]

May I propose renaming p6doc to rakudoc?

[JJ]

Yep, we should definitely do that. Thanks.

[sumanstats]

👍 for rakudoc

[tbrowder]

This issue is now mentioned inside p6doc where it emphasizes p6doc's impending deprecation. But I think this issue is now very confusing because of all the perl6 language. Shouldn't this be closed, cleaned up, and reoponed as a new issue (or document)?

[JJ]

We should definitely update. It's better to clean it up while it's open, I guess

[softmoth]

Here's a proof-of-concept of a rename to rakudoc with Travis CI working, too: https://travis-ci.com/github/softmoth/rakudoc/builds/170393209

I got a little carried away, my original goal was just to see what the rename would entail, but then I wanted to get the tests working, etc.

There's a bit more cleanup that needs to be done, I think. The https://github.com/noisegul/perl6-p6doc/ repo from last summer was left with a few pieces of unused code and a few quick fixes (e.g., how the pager is called), but it's not too far from ready. I'd like to help get it going.

[JJ]

@softmoth you've done amazing work, and you have helped a lot already. But let me know what you want. Since you've already forked and are already working on it, do you want to continue working on it in that repo? Do you want to make it "official" by moving it to the Raku org?

[softmoth]

rakudoc is official, now. It should be mostly usable, but I'm not ready for bug reports quite yet. The most glaring issue at the moment is that ONLY finds /doc//.pod6 files basically, so rakudoc JSON::Fast doesn't work. But there are a number of other smaller issues that I'm working through.

I could use some guidance on how to integrate this into the community. I.e., once it's stable does it go into Rakudo Star? Built into Windows packages? Etc. But that can be discussed later.

Also, I'm not sure if Documentable::Registry's cache should be used directly, or if we should persist with rakudoc managing its own per-user cache (presently in $XDG_CACHE_HOME/raku/rakudoc-index.json). I know there have been a few issues on various projects discussing it (Raku/doc# 3202 links to some), but haven't seen a definitive plan I should hew to.

[JJ]

@softmoth I think one of the main things is to list rakudoc as provided by your module, and not this repo. The rest will be done organically.
Also, I very much prefer rakudoc to use Documentable::Registry cache. It was created precisely for that, and even if it changes in the future in implementation, it should be able to respond do those specs.

[softmoth]

I've updated this Version 2.0 Roadmap to say "Raku" instead of "Perl 6", mutatis mutandis.

I've added "provides" : { "rakudoc" : "bin/rakudoc" } to rakudoc. Any further issues I have w/ indexing, install, etc. I will open over there.

[JJ]

Thanks, @softmoth.

[coke]

To close out this milestone, we will go live with the new https://github.com/raku/doc-website instance and then consider opening new milestones as needed. Going live with that site will finally separate the website from the docs themselves, however, and in spirit close out the issue.

[coke]

Depends on https://github.com/Raku/doc-website/milestone/1

[coke]

I've linked the related milestone here, closing this ticket now, even though the new site is expected to go live in 2 weeks.