Skip to content
Documentation API: caching, parsing, indexing and generating documentation
Perl 6 JavaScript CSS HTML Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Updates zef indices to get the latest versions Sep 3, 2019
.github/ISSUE_TEMPLATE Update issue templates Jul 19, 2019
bin Strip out Perl6::, fix #11 Aug 29, 2019
docs Adds an example of config.json Nov 17, 2019
lib Adds test for kinds in Config refs #68 Dec 1, 2019
resources Bumps up version Dec 1, 2019
t
template Fixes and tests search_template.js in the local dir closes #67 Dec 1, 2019
.gitignore template directory should probably be shown Nov 24, 2019
.travis.yml use jj docker container for testing Jun 8, 2019
CHANGELOG.md
Documentable.iml Minor grammar changes Sep 2, 2019
LICENSE init using App::Mi6 May 22, 2019
META6.json
Perl6-Documentable.iml
README.md More README.md reformatting and grammar corrections Nov 24, 2019
TODO.md answer todo questions Aug 11, 2019

README.md

Documentable, the Perl6 Doc API CI Status Build Status artistic

In this repository you can find all logic responsible for generating the official documentation of Perl6 or any other repository that follows the same specification. Could be used for modules that include a substantial amount of documentation, for instance.

Table of contents

Installation

$ zef install Documentable

If you have already downloaded this repo,

$ zef install .

Usage

This application uses a series of template and asset files (CSS, svg, ...) in order to generate the pages. If your repository does not include them, before generating any documents you should execute:

documentable setup

in order to download them. Alternatively, you can add your own. See default templates to get more information.

Usage:
  bin/documentable setup [-y|--yes] -- Downloads default assets to generate the site
  bin/documentable start [--topdir=<Str>] [--conf=<Str>] [-v|--verbose] [-c|--cache] [-p|--primary] [-s|--secondary] [--search-index] [-i|--indexes] [-t|--typegraph] [-f|--force] [--highlight] [--typegraph-file=<Str>] [--highlight-path=<Str>] [--dirs=<Str>] [-a|--all] -- Start the documentation generation with the specified options
  bin/documentable update [--topdir=<Str>] [--conf=<Str>] [-v|--verbose] [--highlight] [--highlight-path=<Str>] -- Check which pod files have changed and regenerate its HTML files.
  bin/documentable clean -- Delete files created by "documentable setup"
  bin/documentable [-V|--version] -- Documentable version

    -y|--yes                  Always accept the operation (to use in scripts)
    --topdir=<Str>            Directory where the pod collection is stored
    --conf=<Str>              Configuration file
    -v|--verbose              Prints progress information
    -c|--cache                Enables the use of a precompiled cache
    -p|--primary              Generates the HTML files corresponding to primary objects
    -s|--secondary            Generates per kind files
    --search-index            Generates the search index
    -i|--indexes              Generates the index files
    -t|--typegraph            Write typegraph visualizations
    -f|--force                Force the regeneration of the typegraph visualizations
    --highlight               Highlights the code blocks
    --typegraph-file=<Str>    TypeGraph file
    --highlight-path=<Str>    Path to the highlighter files
    --dirs=<Str>              Dirs where documentation will be found. Relative to :$topdir
    -a|--all                  Equivalent to -t -p -s -i --search-index

See the CLI documentation to learn more.

Default templates

As you may have noticed, every page in the documentation follows the same template. You can get those templates in the releases page. We strongly recommend you to use the defaults, which can be set up executing

documentable setup

That command will download the latest assets tarfile in your directory. But what does this tar contain? Several things:

  • Necessary files to enable highlighting (highlights dir).
  • The html dir containing several icons, graphics, etc. All HTML documents generated by Documentable will be stored here.
  • assets dir containing the style sheets used and JS code to enable search functionality.
  • template dir containing the default templates used.
  • Two files to run the server (app-start and app.pl).
  • A Makefile to configure highlighting (make init-highlights) and easily start a dev server with make run.

Docker container

There is a specific docker container with all necessary dependencies (including the highlighter) at https://github.com/antoniogamiz/docker-documentable.

You can see an example about how to use it here.

You can also download the container:

docker pull antoniogamiz/documentable

Then execute:

docker run -it --rm -v "$(pwd)":/documentable antoniogamiz/documentable

And now you can execute documentable and generate your documentation!

Note: Do not forget to add --highlight --highlight-path="/highlights" options if you want to get the code highlighted.

Installing dependencies

Rakudo

You need Perl 6 installed. You can install the Rakudo Perl 6 compiler by downloading the latest Rakudo Star release from rakudo.org/downloads/star/.

zef

Zef is a Perl 6 module installer. If you installed Rakudo Star package, it should already be there. Feel free to use any other module installer for the modules needed (see below).

Mojolicious / Web Server (OPTIONAL)

Mojolicious is written in Perl 5, so assuming that you use cpanm, install this now:

    $ cpanm -vn Mojolicious

GraphViz

To generate the svg files for the typegraph representation you need to have installed graphviz. If you use Ubuntu/Debian:

    $ sudo apt-get install graphviz

Highlight (OPTIONAL)

This is necessary to apply highlighting to the code examples in the documentation. You can skip it, but have in mind that all code examples will appear with the same color (black).

You can set this up with the default Makefile (obtained using documentable setup):

    make init-highlights

SASS Compiler

To build the styles, you need to have a SASS compiler. You can either install the sass command

    $ sudo apt-get install ruby-sass

wget and tar

These programs are used by documentable setup to download the default assets and extract them. If you are on Ubuntu/Debian you will not have any problem (probably). If you are using Windows I recommend you to download the assets yourself from this link.

FAQ

Question: Do I need to regenerate all pages when I have only changed one?

Answer: No, you can execute documentable update to only regenerate those pages affected by your changes.

Is not your question here? Then, please raise an issue.

AUTHORS

Antonio Gámiz Delgado <@antoniogamiz>

Moritz Lenz <@moritz>

Jonathan Worthington <@jnthn>

Richard Hainsworth<@finanalyst>

Will Coleda <@coke>

Aleks-Daniel <@AlexDaniel>

Sam S <@smls>

Juan Julián Merelo Guervós <@JJ>

MorayJ <@MorayJ>

Zoffix <@zoffixnet>

Tison <@TisonKun>

Samantha Mcvey <@samcv>

Altai-Man <@Altai-man>

Tom Browder <@tbrowder>

Alexander Moquin <@Mouq>

Wenzel P. P. Peppmeyer <@gfldex>

COPYRIGHT AND LICENSE

Copyright 2019 Perl6 Team

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

This module uses some conventions: (this started in August, 2019, so previous work does not follow the conventions):

We use a ChangeLog generator to generate the CHANGELOG.md file.

You can’t perform that action at this time.