txt: ## dist_github-Raku-Documentable.md
  # Documentable, the Raku Doc API [CI Status](https://circleci.com/gh/Raku/Documentable) [Build Status](https://travis-ci.org/Raku/Documentable) [Build Status](https://dev.azure.com/antoniogamiz10/Documentable/_build/latest?definitionId=1&branchName=master) [artistic](https://opensource.org/licenses/Artistic-2.0)
  
  In this repository you can find all logic responsible for generating the
  [official Raku documentation](https://docs.Raku.org/) 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).
  
  ## Table of contents
  
  * [Installation](#installation)
  * [Usage](#usage)
  * [Documentation](https://raku.github.io/Documentable/)
  * [Docker container](#docker-container)
  * [Tests](#%C5%A7ests)
  * [FAQ](#faq)
  * [Authors](#authors)
  
  ## Installation
  
  ```
  $ zef install Documentable
  
  ```
  
  If you have already downloaded this repo,
  
  ```
  $ zef install .
  
  ```
  
  ## Usage
  
  Documentable uses a [Mustache](https://mustache.github.io/) 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](https://github.com/raku/Documentable/releases/download/v1.0.1/assets.tar.gz) in your directory. This tar contains:
  
  * 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 template used.
  * A `type-graph.txt` example 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](https://raku.github.io/Documentable/language/cli) to learn more, or [the documentation on `documentable.json`](https://raku
  .github.io/Documentable/language/configuration-file) to create your own
  configuration file.
  
  ## 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](https://github.com/raku/Documentable/blob/master/.circleci/config.yml).
  
  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 Raku installed. You can install the Rakudo Raku compiler by
  downloading the latest Rakudo Star release from
  [rakudo.org/downloads/star/](http://rakudo.org/downloads/star/) or the
  latests releases via [Rakubrew](https://rakubrew.org/).
  
  #### `zef`
  
  [Zef](https://modules.raku.org/repo/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 / Web Server (OPTIONAL)
  
  Mojolicious is written in Perl 5, so assuming that you use
  [`cpanm`](https://metacpan.org/pod/App::cpanminus),
  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
  
  ```
  
  #### Node & Highlight
  
  This is necessary to apply highlighting to the code examples in the
  documentation. We use [Atom highlighting](https://github.com/perl6/atom-language-perl6), so you will need to install [Node.js](https://nodejs.org/en/).
  
  You can set the highlighter 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 need to install
  the `sass` command
  
  ```
      $ sudo apt-get install ruby-sass
  
  ```
  
  #### `curl` 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 (probably) not
  have any problem. If you are using Windows I recommend you to download
  the assets yourself from
  [this link](https://github.com/raku/Documentable/releases/download/v1.0.1/documentable-assets.tar.gz).
  
  ## 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 your question not here? Then, please [raise an issue](https://github.com/raku/Documentable/issues/new).
  
  # 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, 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](https://github.com/github-changelog-generator/github-changelog-generator) to generate the [CHANGELOG.md file](CHANGELOG.md).
  