archeos-manual package

ArcheOS logo

This page describes the state of art and process related the ArcheOS documentation project

Overview

Documentation for ArcheOS is built from a single git repository. This means that both the archeos-manual package and the documentation browsable online are built using Sphinx using quite the same steps.

How to build the package (standard)

Warning

This section is common to all “simple” archeos packages.

  1. Edit the debian/control file and do the relative modifications (add package to depends, and so on).
  2. You can test the package build with git-buildpackage --git-ignore-new anytime you want.
  3. When ready to deploy a working version, commit your changes the usual way (git add & git commit).
  4. Use git-dch -R to update the changelog file. Edit it properly (if need to change something, but most of the time it doesn’t.) then add it and commit it too (usual git add and git commit).
  5. Build and tag the package with git-buildpackage --git-tag. Push changes upstream with git push && git push --tags
  6. Clean the package with debuild clean.
  7. Upload the packages (all deb files, changes and dsc) to the repository server and import them into the distrubution with reprepro.

Package

The package is fairly simple, due to the use of custom debian helper sphinxdoc option (see debian/rules).

All information on how to build html pages, man pages, and so on are contained into the Makefile. The current targets are html and man.

The documentation is written in reStructuredText (rst) format, a quick primer on the syntax for Sphinx can be found here. All files can be found into the source/ folder within the package.

The documents in the source/ are organized in a clear way:

  • The applications/ folder is the documentation relative to all applications installed into ArcheOS, specifying eventual changes made by ArcheOS developers and other significant information. One rst file per application should be created into the applications/pages/ folder. As stated into the index, use the Application template to create new application page.
  • The tutorials/ folder is used for guides and tutorials. Like applications, is suggested to create one page per tutorial into the tutorals/pages/ folder following the Tutorial template guidelines.
  • The development/ folder contains information for ArcheOS developers, how to build packages, caveats, instructions on how to customize the distribution and so on. Is intended mainly to remember us the usual procedures and track changes in ArcheOS. Also there the usual page/ structure is used, with one page per package/guide/other.

Other files/folders

  • _static/ contains static files (js/images)
  • _templates/ contains the Sphinx template (defined into conf.py)
  • conf.py contains the general directives for Sphinx (see the documentation about)
  • global.rst in sincluded in most pages and contains the image (logo). Contains also some cross-pages features.

Online documentation

The same package that generates the ArcheOS html/man pages is used to build the online documentation (included this page you are probably reading on the ArcheOS website).

On doc.archeos.it website you can easily browse the html pages generated by Sphinx. Just remember that if a developer updates this package and does not update it on the server, probably the online version could be outdated towards the one installed on ArcheOS boxes.

Contribute to the documentation

If you want to contribute with fixes, application pages, tutorials or any other ideas, you can fork this repository on GitHub and send us a pull request!

Fork me on GitHub