Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/raku/documentable-backup
Raku documentation CLI and API
https://github.com/raku/documentable-backup
Last synced: 6 days ago
JSON representation
Raku documentation CLI and API
- Host: GitHub
- URL: https://github.com/raku/documentable-backup
- Owner: Raku
- License: artistic-2.0
- Created: 2020-01-24T12:08:54.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-01-24T12:10:31.000Z (over 4 years ago)
- Last Synced: 2024-09-22T21:02:18.872Z (11 days ago)
- Language: Perl 6
- Size: 778 KB
- Stars: 1
- Watchers: 9
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Documentable, the Perl6 Doc API [](https://circleci.com/gh/perl6/Documentable) [](https://travis-ci.org/perl6/Documentable) [](https://opensource.org/licenses/Artistic-2.0)
In this repository you can find all logic responsible for generating the
[official documentation of Perl6](https://docs.perl6.org/) 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](#installation)
- [Usage](#usage)
- [Documentation](https://perl6.github.io/Documentable/)
- [Docker container](#docker-container)
- [Default templates](#default-templates)
- [Tests](#ŧests)
- [FAQ](#faq)
- [Authors](#authors)
## 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](#default-templates) to get more information.
```
Usage:
bin/documentable setup [-y|--yes] -- Downloads default assets to generate the site
bin/documentable start [--topdir=] [--conf=] [-v|--verbose] [-c|--cache] [-p|--primary] [-s|--secondary] [--search-index] [-i|--indexes] [-t|--typegraph] [-f|--force] [--highlight] [--typegraph-file=] [--highlight-path=] [--dirs=] [-a|--all] -- Start the documentation generation with the specified options
bin/documentable update [--topdir=] [--conf=] [-v|--verbose] [--highlight] [--highlight-path=] -- 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= Directory where the pod collection is stored
--conf= 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= TypeGraph file
--highlight-path= Path to the highlighter files
--dirs= Dirs where documentation will be found. Relative to :$topdir
-a|--all Equivalent to -t -p -s -i --search-index
```
See the [CLI documentation](https://perl6.github.io/Documentable/language/cli) 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](https://github.com/perl6/Documentable/releases/tag/v1.0.1). We
strongly recommend you to use the defaults, which can be set up executing
```
documentable setup
```
That command will download
the
[latest assets tarfile](https://github.com/perl6/Documentable/releases/download/v1.0.1/assets.tar.gz) 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](https://github.com/perl6/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 Perl 6 installed. You can install the Rakudo Perl 6 compiler by
downloading the latest Rakudo Star release from
[rakudo.org/downloads/star/](http://rakudo.org/downloads/star/).
#### `zef`
[Zef](https://modules.perl6.org/repo/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`](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
```
#### 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](https://github.com/perl6/Documentable/releases/download/v1.0.1/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 not your question here? Then, please [raise an issue](https://github.com/perl6/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 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):
- [Semantic Versioning](https://semver.org/).
- [Branching model](https://nvie.com/posts/a-successful-git-branching-model/).
- [Commit names](https://chris.beams.io/posts/git-commit/).
We use a [ChangeLog generator](https://github.com/github-changelog-generator/github-changelog-generator) to generate the [CHANGELOG.md file](CHANGELOG.md).