Docs Italia is the place where public digital documents can be published and browsed. It offers to the public entities a secure and feature-complete platform for publishing documents and it offers to citizens tools for searching and browsing documents, that can be accessed from any device.
Docs Italia simplifies the publishing process: documents use a version control system as data source, encouraging collaborative editing and allowing the community to perform analysis and comparisons between different versions.
The generation tool behind Docs Italia is Sphinx, which supports several markup languages among which RestructuredText and MarkDown. We’re working for improving the platform according to the needs detected during the first test year: the document converter, the publishing flow and search/browsing tools. We use Pandoc for converting documents from the most used formats, like
A first relase of Docs Italia was completed during 2018, and more features are scheduled for the next months. he platform is based on the well known open source project ReadTheDocs, which serves as a basis for secure identity management of organizations and editors.
These are the main tasks scheduled for the near future:
- Improvement of the search engine based on ElasticSearch by adding the ability to filter by popularity, publisher, tags, projects.
- Finalization of the API for getting data and metadata of documents.
- Handling of controlled vocabularies for tagging contents and improvement of navigation between related documents.
- Improvement of the frontend interface, according to the designs.
- Simplifcation of the onboarding process and the administration/publishing backoffice.
- Improvement of the infrastructure and log handling, and improvement of disaster recovery strategy.
- Whitelabel features for organizations: we want to enable organizations to customize their page and use their own domains as well as embed contents from Docs Italia in their website.
If you have ideas for this project, or you think you can help about these features, contact us in the forum or in Slack. Everyone can contribute!
Il codice sorgente di Docs Italia è diviso in alcuni repository a seconda del dominio su cui insistono:
- The Docs Italia platform, a fork of ReadTheDocs, written in Python and Django.
- The Ansible scripts for deploying the platform.
- The Django app with the web converter.
- Pandoc filters.
- Commands for converting documents with Pandoc (in Haskell).
- A starter kit containing files for publishing new documents.
- The Sphinx theme which is applied by default to documents.
- Document tempates in several formats.
Each document visible on Docs Italia has a corresponding GitHub repository, whose link is included in the website header.
Documentation for Docs Italia is published in Docs Italia itself! ;-)
A special document is the Docs Italia Guide, which explains how each public organization can create its account and publish a document. If you want to publish contents on Docs Italia you can start here:
In the document you’ll find the contacts of our tech writers who can help you in setting up the platform for your organization and writing or converting documents.
More technical information can be found in the README files of single repositories, and in the main repository wiki.