develooper Front page | perl.perl6.users | Postings from August 2019

Refactoring of the documentation system.

From:
Richard Hainsworth
Date:
August 26, 2019 10:14
Subject:
Refactoring of the documentation system.
Message ID:
18792e9a-98b3-753c-a082-a3a2935b706e@gmail.com
General notification!

The community members working on the documentation system are deploying 
a new refactored system. Hopefully, no one will notice a difference on 
the docs.perl6.org page. When the next Rakudo Star is released p6doc 
will be working.

However, murphy rules! So some warning ...

The Perl 6 documentation system has developed incrementally over several 
years. Problems developed, the most obvious being that p6doc stopped 
working.

Two GSoC projects have refactored the system and p6doc works in a much 
more intuitive manner.

A number of modules are all in a single repository, and these need to be 
split, so that the base Pod6 sources containing documentation about the 
language are in one repo, p6doc is in another repo, and support modules 
are in other repos.

The main aim of the new work has been

- retain the user-facing interface

- specify the documentation system so that changes to the documentation 
software can be tested

- unit tests on software and the documentation

- increased robustness of the documentation system

All of this development work and the rational behind it can be found in 
the wiki at the github repo for the docs.

The refactoring has been tested separately, but it will be implemented 
for the Perl 6 system in the near future.

Some patience is requested.

In order for Perl 6 to be more widely accepted, it must have a good and 
evolving documentation system. As new functionality becomes common in 
the software world, the documentation system needs to adapt.

By separating out content sources from the software rendering the 
sources, we can allow for new systems to develop.

Not everyone agrees about what is 'good' documentation. So for the 
future, flexibility is needed to allow for different possibilities to be 
developed based on a single set of source POD6 files, and for software 
to be specified and tested before deployment.

Regards,

Richard Hainsworth,

aka finanalyst



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About