### ----------------------------------------------------
### -- Documentable
### -- Licenses: Artistic-2.0
### -- Authors: @moritz, @finanalyst, @tbrowder, @AlexDaniel, @antoniogamiz, @JJ
### -- File: README.md
### ----------------------------------------------------
# Documentable, the Raku Doc API [![CI Status](https://circleci.com/gh/Raku/Documentable.svg?style=shield)](https://circleci.com/gh/Raku/Documentable) [![Build Status](https://travis-ci.org/Raku/Documentable.svg?branch=master)](https://travis-ci.org/Raku/Documentable) [![Build Status](https://dev.azure.com/antoniogamiz10/Documentable/_apis/build/status/Raku.Documentable?branchName=master)](https://dev.azure.com/antoniogamiz10/Documentable/_build/latest?definitionId=1&branchName=master) [![artistic](https://img.shields.io/badge/license-Artistic%202.0-blue.svg?style=flat)](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](#ŧests)
- [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).


