This page describes the state of art and process related the ArcheOS documentation project
How to build the package (standard)
This section is common to all “simple” archeos packages.
- Edit the debian/control file and do the relative modifications (add package to depends, and so on).
- You can test the package build with git-buildpackage --git-ignore-new anytime you want.
- When ready to deploy a working version, commit your changes the usual way (git add & git commit).
- 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).
- Build and tag the package with git-buildpackage --git-tag. Push changes upstream with
git push && git push --tags
- Clean the package with debuild clean.
- Upload the packages (all deb files, changes and dsc) to the repository server and import them into
the distrubution with reprepro.
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
- 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.
- _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
- global.rst in sincluded in most pages and contains the image
(logo). Contains also some cross-pages features.
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
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!