Commit aabe8be1 authored by Mathieu Duponchelle's avatar Mathieu Duponchelle Committed by Mathieu Duponchelle

Initial checkin

parents
{
"phabricator.uri": "https:\/\/phabricator.apertis.org\/",
"project": "Apertis designs",
"default-reviewers": "#reviewers"
}
/build
/hotdoc-private*
# Introduction
This repository contains the design documents written by Collabora
and Bosch engineers for the Apertis platform.
These documents were previously libreoffice files managed
by SparkleShare, they have been translated to markdown
in June 2016. Archives for previous versions of these documents
can still be found in epoisses.collabora.co.uk/git/bosch-proposals.git.
# Contributing
## Style
We follow the commonmark specification, extended by hotdoc's
table extensions (github-flavored pipe tables).
We prefer reference links at the bottom of individual
documents instead of inline.
We will try to follow this
[style guide](http://www.cirosantilli.com/markdown-style-guide/#about),
and are still [evaluating solutions](https://github.com/jgm/cmark/issues/131)
for *stable* automatic formatting.
80 columns line width is thus not yet enforced, but strongly suggested.
## Writing a new design document
`docs/geolocation-and-navigation.md` is an example of a well-written
design document.
Generally speaking, a new design document should:
1. Contain a brief introduction summarizing its purpose
2. Define terminology (such as acronyms) and concepts it will commonly reference.
3. Expose the use cases it will attempt to solve, and use cases that could
have been in scope but were explicitly left out.
4. Even though it's not part of the example document, a short section
on the security model can be helpful, even just to say there is none.
5. Formulate requirements, derived from the use cases
6. Study of existing solutions, showing how they (do not) address the
listed use cases and requirements.
7. Present the proposed approach in detail. Having defined clear use cases
and documented existing solutions lets us reference them heavily in this
section.
8. Go over the initial list of requirements, and show how the proposed
design(s) fulfil or fail them.
9. Summarize the questions that remain open, to ease future improvement
10. Summarize the recommendations that the proposed approach made.
## Submit your changes
We will use the [standard contribution process](https://wiki.apertis.org/Guidelines/Contribution_process).
# Build the web portal locally
## Install dependencies
* Follow [hotdoc's installation guide](https://people.collabora.com/~meh/hotdoc_hotdoc/html/installing.html),
preferably in a virtualenv.
* Install the `hotdoc_syntax_highlighting_extension`:
```
pip install hotdoc-syntax-highlighting-extension
```
* Optionally install the `hotdoc_search_extension`:
```
pip install hotdoc-search-extension
```
* Build the portal:
```
hotdoc run
```
* And browse it:
```
xdg-open build/html/index.html
```
This source diff could not be displayed because it is too large. You can view the blob instead.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
# Apertis design portal
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
{
"index": "docs/index.md",
"output": "build",
"sitemap": "sitemap.txt",
"extra_assets": ["media"],
"syntax_highlighting_activate": true
}
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment