Status: Still a work in progress

Web: https://taigaio.github.io/taiga-doc/dist/

Install requirements: Ruby / asciidoctor + pygments.rb (installed via. bundler using the provided Gemfile)

You can install Ruby through the apt package manager, pacman, rbenv, or rvm.

Confirm that Gemfile is in the base taiga-doc directory, and then perform the installation from that directory:

$ cd taiga-doc
$ export PATH=$(ruby -e "print Gem.user_dir")"/bin:$PATH"
$ export GEM_HOME=$(ruby -e 'print Gem.user_dir')
$ gem install bundler
$ bundle
$ asciidoctor -v // should return Asciidoctor 1.5.1 ...

Taiga doc includes a django app that helps us generate the curl commands and the json responses from the api. To use it, you have to activate your taiga-back virtualenv, and install the generate_api_documents.

$ workon taiga
$ cd generate_api_documents_app
$ pip install -e .

Now add it to your taiga settings installed apps; Modify in taiga-back your settings/local.py and include the line:

INSTALLED_APPS += ["generate_api_documents"]

For generating api examples you need to disable DEBUG option in your settings as well as enable the following importers:

IMPORTERS["github"]
IMPORTERS["trello"]
IMPORTERS["jira"]
IMPORTERS["asana"] 

If you copied local.py.example, uncommenting the importers code should be enough.

Now regenerate the taiga-back database with the sample data:

$ cd taiga-back
$ workon taiga
$ bash regenerate.sh
$ python manage.py runserver

And finally, in a new terminal, run the generate_api_examples django command:

$ cd taiga-back
$ workon taiga
$ python manage.py generate_api_examples

If you get some error, check your settings and regenerate the database again.

After that, you have to copy the content generated in the output directory to the api/generated/ directory in taiga-doc:

$ mv output/* ../taiga-doc/api/generated/

Now you can rebuild your documentation running make:

$ make

Prerequisite: Initial environment above must be setup and working

This step is optional but highly recommended in order to ease the process of editing AsciiDoc files, by rendering the HTML from the source .adoc file as soon as any modifications are saved - allowing for instant preview in the browser.

The following instructions are based on:

• The Asciidoctor page: Editing AsciiDoc with Live Preview
• The Guard README: Guard: README.md

If the bundler install completed successfully, all of the gems will already be in place (including both Guard and the shell file monitor).

For notifications to work properly:

You have to install the libnotify-bin package with your favorite package manager

-- Guard: System notifications - Libnotify

For example, on a Debian-based system:

$ sudo apt-get install libnotify-bin

Or in Arch

$ yaourt -S libnotify

It's important that you always run Guard through Bundler to avoid errors.

-- Guard: README.md

Confirm that Guardfile is in the base taiga-doc directory and then start Guard from that directory:

$ cd taiga-doc
$ bundle exec guard

• Open index.adoc in a text editor, make a minor modification and then save the file
• If Guard is working properly, dist/index.html will be created/updated automatically
• If libnotify is configured correctly, a notification will be shown confirming that index.adoc has been found and rendered accordingly

Note: The Asciidoctor page suggests using LiveReload with the guard-livereload gem but this package is no longer compatible with LiveReload 2

Simply use a browser that has auto-reload built-in or install a relevant browser add-on.

Examples include:

• Web web browser (formerly Epiphany web browser) - has built-in auto-reload functionality
• Firefox + Auto Reload add-on
• [Please add other working configurations here]

• Open dist/index.html in the browser
• As before, save a modification to index.adoc
• Once Guard has rendered the new copy of dist/index.html, the browser will auto-reload the page

Some tips/notes about working with live preview:

• Position the text editor and web browser windows side-by-side (or on different screens!), save changes and see the result in the browser almost immediately
• Changes to any of the .adoc files within the api/ directory or its sub-dirs will render dist/api.html - since many .adoc files are combined to render the single HTML file, there is a slight lag in the live preview as the conversion process completes
• Otherwise, there is a 1:1 relationship between the .adoc file and its rendered .html file - changes to these are displayed almost instantaneously