Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Version 2.0 Roadmap #2983

Open
JJ opened this issue Aug 28, 2019 · 4 comments

Comments

@JJ
Copy link
Contributor

commented Aug 28, 2019

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 perl6 organization, so that anyone can work on them (this might include a change of name)

  • 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 p6doc tools to a different repository.

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

  • perl6/doc will contain just the documentation and tests related to it.

  • perl6/Documentable will contain the documentable script and modules.

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

  • perl6/p6doc 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.

@JJ JJ added build meta labels Aug 28, 2019
@JJ JJ pinned this issue Aug 31, 2019
JJ added a commit that referenced this issue Aug 31, 2019
JJ added a commit that referenced this issue Aug 31, 2019
JJ added a commit that referenced this issue Aug 31, 2019
JJ added a commit that referenced this issue Aug 31, 2019
JJ added a commit that referenced this issue Aug 31, 2019
JJ added a commit that referenced this issue Aug 31, 2019
JJ added a commit that referenced this issue Aug 31, 2019
JJ added a commit that referenced this issue Aug 31, 2019
JJ added a commit that referenced this issue Sep 1, 2019
@coke

This comment has been minimized.

Copy link
Contributor

commented Sep 3, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Sep 3, 2019

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

This comment has been minimized.

Copy link
Contributor Author

commented Sep 3, 2019

@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

This comment has been minimized.

Copy link
Contributor Author

commented Sep 3, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.