In this repository you can find all logic responsible for generating the official Raku documentation or any other repository that follows the same specification. Could be used for modules that include a substantial amount of documentation, for instance (as long as the layout of the different parts is still the same).
$ zef install Documentable
If you have already downloaded this repo,
$ zef install .
Documentable uses a Mustache template and several asset files. So, in order to generate the pages, you need to have these files in your working directory. You can get them with:
documentable setup
That command will download the latest assets tarfile in your directory. This tar contains:
- Necessary files to enable highlighting (
highlightsdir). - The
htmldir containing several icons, graphics, etc. All HTML documents generated byDocumentablewill be stored here. assetsdir containing the style sheets used and JS code to enable search functionality.templatedir containing the default template used.- A
type-graph.txtexample file.
Usage:
bin/documentable setup [-o|--override] -- 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, or [the documentation on documentable.json](https://raku
.github.io/Documentable/language/configuration-file) to create your own
configuration file.
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.
You need Raku installed. You can install the Rakudo Raku compiler by downloading the latest Rakudo Star release from rakudo.org/downloads/star/ or the latests releases via Rakubrew.
Zef is a Raku module installer. If you installed Rakudo Star package, it should already be there. Feel free to use any other way to install the modules needed (see below).
Mojolicious is written in Perl 5, so assuming that you use
cpanm,
install this now:
$ cpanm -vn Mojolicious
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
This is necessary to apply highlighting to the code examples in the documentation. We use Atom highlighting, so you will need to install Node.js.
You can set the highlighter up with the default Makefile (obtained using documentable setup):
make init-highlights
To build the styles, you need to have a SASS compiler. You need to install
the sass command
$ sudo apt-get install ruby-sass
These programs are used by documentable setup to download the default assets
and extract them. If you are on Ubuntu/Debian you will (probably) not
have any problem. If you are using Windows I recommend you to download
the assets yourself from
this link.
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 your question not here? Then, please raise an issue.
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 2019, 2020 Raku Team
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
We use a ChangeLog generator to generate the CHANGELOG.md file.