Online Tilia User Manual

This repository is the source text for the Tilia Manual which support the Tilia software.

Authors

• Jessica Blois
• Simon Goring
• Daniela Alvarado Flores -- University of California, Merced
• Neotoma Development Team https://neotomadb.org

We welcome contributions from any individual, whether code, documentation, or issue tracking. All participants are expected to follow the code of conduct for this project.

License

The original documentation herein is licensed under an MIT license. This Documentation makes use of Sphinx and ReStructuredText. Sphinx is licensed under a BSD license.

Development

The manual is scripted using plain-text files with ReStructuredText markdown all saved in the docs folder (with an rst extension). readthedocs uses a workflow where documents generated in rst files are then compiled to HTML using a Python parser called Sphinx to generate the documentation. Once the file is compiled it is then pushed up to the GitHub repository (you're here now) and is then cloned & re-compiled by readthedocs, where it becomes available at .

Currently the files within the manual are structured (somewhat) hierarchically:

• index.rst : The header for the documentation. Compiles here. Contains the Acknowledgements and the Table of Contents. Acts as a simple homepage for the Manual.
• get_tilia.rst : Downloading & Installation instructions for Tilia. Compiles here
• creating : How to create a new Tilia file. Compiles here
• overview.rst : Presumes that a file has been generated. An overview of an empty Tilia file. Compiles here
• edit_data.rst : How to go about editing a Tilia file. Both practical and best-practices. Compiles here
• tools.rst : Still a stub. This is intended to present the various features of Tilia that aren't part of the core editing process. Compiles here
• steward.rst : Proposed but not developed.

Remote Builds

The readthedocs website automatically tracks this GitHub repository so that each new push to the main branch of this repository triggers the website to rebuild the manual. Thus, new updates can be immediately seen on the website once either (1) a change is pushed directly to the main branch, or (2) a branch is merged into the main branch through a pull request.

Users who wish to see changes locally before pushing to the repository can build and serve the documentation on their own computers following the directions below:

Local Builds

To build locally you must have Sphinx installed. Sphinx is a Python based application, and instructions for installing sphinx are available here.

Once you have ensured that Sphinx is installed you can proceed to the next step.

The folder docs contains two Makefile type objects. Once, called Makefile and the other called make.bat. The Makefile is for Linux-based OSs, including MacOS. A Makefile can be executed using the command make followed by a target. Executing make in the docs directory will bring up a set of options available as targets. These include html, epub, and latexpdf. To see how the documentation will look (approximately) on readthedocs, you can execute:

make html

You should see output similar to:

$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v3.2.1
WARNING: html_static_path entry '_static' does not exist
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded, 1 warning.

The HTML pages are in _build/html.

Build finished. The HTML pages are in _build/html.

At this point you can open the ~/tilia-manual/docs/_build/html/index.html file in your browser to see the current representation of the document. You can navigate through the document, and re-run make html any time you make changes to see the current version.