Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The network development document is incomplete, missing out instructions
for setting up NFS and TFTP:

- Add these sections
- Lightly rework the document to improve wording and layout
- Move to guides section

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

The VirtualBox documentation from developer.apertis.org broadly covers the
same topics as the VirtualBox documentation the already existed on the main
website. Merge these together. Topics not closely tied to VirtualBox have
been moved to other pieces of documentation where they are better suited.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

The API quicklinks haven't been maintained and basically replicate the list
provided in `apis.md`. Remove this list to reduce duplication.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

The installation document is a part of the "vm-" prefixed series of documents.
Rename it to make this more obvious.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

The developer documentation contains a whole load of documents covering
the technologies available in Apertis. These are very minimal. Merge these
documents together for now.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

The developer documentation contains a number of documents that are
duplicated from the wiki. Remove the duplications, ensuring the remaining
copies are up-to-date.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

We now have a copy of the developer docs on the website, point to them
rather than developer.apertis.org (which should soon be redirected).

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

Clean up the titles and formatting of the documents as a recursor to a
more detailed review and sorting of the documents.

Remove unneeded arrow image as it's no longer used on any of the pages.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

Pull the example debos recipes into the documentation. HotDoc allowed
these examples to be held in separate files. Hugo doesn't provide this
functionality by default, so for now include inline in the relevant
document. This doesn't really hurt ans they were only included into one
document anyway.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The metadata in each file on developer.apertis.org didn't contain a
creation date, however this is the primary means that we are ordering the
documents by on the new Apertis website so that the newer documents are
listed first.

Whilst the documents don't contain a creation date, they are stored in a
git repository that can provide us with this information. Add the
retrieved dates into the front matter.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

Some of the documents contain markup that HotDoc uses differently, or for
which we have a better alternative. Start change the usages found so far.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

There are 2 internationalisation documents, we need to detail which one we
mean in the link that uses it.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The developer documentation contains URLs to designs.a.o and the old wiki.
The website contains links to the developer site. Now that these are all
on the same site, update links to internal links.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The developer document contains links to an `app-distribution.md` document
that doesn't exist. Point to the legacy canterbury documentation for now.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

Hugo provides a short code that allows us to perform some checks on links
at build time. Use it.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

A quick first pass to clean up the developer index page.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

Both the developer and designs documentation contain a file named
"multimedia.md`. Tweak the path used in the documentation to remove the
ambiguity.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The developer documentation is now in it's own temporary section. Move the
index page to the correct name for a section index.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The existing metadata and some inline codes need converting to work with
Hugo:

 - Remove authors as we don't have an equivalent for that in Hugo
 - Add in fields that the existing metadata doesn't have
 - Include aliases to allow us to point to the new pages from a
   redirect on designs.apertis.org
 - Ensure we have a title (based on filename if one not present)
 - Convert hotdoc code blocks to Hugo equivalent
 - HotDoc allowed a `[][link]` format that Hugo doesn't understand
 - HotDoc allowed relative links without text, which Hugo doesn't handle
 - The location of the images and other media has changed
 - The format used for internal page references has is different

Additionally, fix up touched links to other Apertis pages to use the
Hugo "ref" shortcode, which reduces the risk of leaving hanging links.

All frontmatter created in toml format to stay consistent with existing
documents.

Converted using the following python script:
```

import os
import re
import subprocess
import sys
import toml
import yaml

def url_munge(match):
    url = match.group('url').strip('.')
    if url[0] != "/":
        url = "/%s" % url
    url = url.replace("media", "images")
    link = ("![](%s)" % url)

    return link

def link_munge(match):
    link = match.group('link')
    new = link.replace("(", "")
    new = new.replace(")", "")
    new = new.replace("`", "")
    new = new.replace("?", "")
    new = new.replace(":", "")
    new = new.replace(",", "")
    new = new.replace("–", "")
    new = new.replace("“", "")
    new = new.replace("”", "")
    new = new.replace(".", "")
    new = new.replace(" ", "-")
    new = new.lower()
    new = (" [%s]( {{< ref \"#%s\" >}} )" % (link, new))

    return new

def link_munge_2(match):
    link = match.group('link')
    new = link.replace("#", "")
    new = new.replace("-", " ")
    new = new.replace(".md", "")
    if not "http" in link:
        link = " {{< ref \"%s\" >}} " % link

    new = (" [%s](%s)" % (new, link))

    return new

for filename in os.listdir("."):
    if ".md" not in filename:
        continue

    print("%s: " % filename)
    with open(filename, 'r+') as file:
        contents = file.read()
        if contents[0:3] == "+++":
            # We have toml
            data = toml.loads(contents.split("+++")[1])
            doc = "+++".join(contents.split("+++")[2:])
        elif contents[0:3] == "---":
            # We have yaml
            data = yaml.load(contents.split("---")[1])
            doc = "---".join(contents.split("---")[2:])
        else:
            # No frontmatter
            data = {}
            doc = contents

        if not "title" in data.keys():
            data["title"] = filename.split(".")[0].replace('_', ' ').capitalize()

        data["weight"] = 100
        data["aliases"] = ["/old-developer/latest/%s" % filename.replace(".md", ".html")]

        # Add aliases
        latest = data['aliases'][0]

        for version in ['v2019', 'v2020', 'v2021pre', 'v2022dev0']:
            versioned = latest.replace("/latest/", "/%s/" % version)
            data['aliases'].append(versioned)

        data["outputs"] = ["html", "pdf-in"]

        # Remove authors
        if "authors" in data.keys():
            del data["authors"]

        # Switch HotDoc code blocks to hugo code blocks
        pattern = re.compile("^---", re.MULTILINE)
        doc = pattern.sub("```", doc)

        # Hotdoc uses `[][Internal Title]` for internal links whilst Hugo uses `[](#internal-title)`
        pattern = re.compile("\[\]\[(?P<link>.*?)\]")
        doc = pattern.sub(link_munge, doc)

        # Hotdoc allows empty links like `[](url)`
        pattern = re.compile("[^!]\[\]\((?P<link>.*?)\)")
        doc = pattern.sub(link_munge_2, doc)

        # Media links not working
        pattern = re.compile("!\[\]\((?P<url>.*?)\)")
        doc = pattern.sub(url_munge, doc)

        file.seek(0)
        file.truncate()

        file.write("+++\n")
        file.write(toml.dumps(data))
        file.write("+++")
        file.write(doc)
```

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

The documentation pulled from developer.apertis.org, which utilises HotDoc
document generation uses a `...` marker at the end of it's leading
metadata whilst Hugo (as used on the website) expects `---`. change
instances of this string.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

This is the initial import of documents and media from
developer.apertis.org. It will need tweaks to make it build properly.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

For external developers, they may not have access right to push branches
into default repositories. We encourage users to fork the repository and
then prepare a merge request.

So updating the documentation accordingly.

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

This commit fixes typos and small issues on the long term
reproducibility document.

Signed-off-by: Peter Senna Tschudin <peter.senna@collabora.com>

Martyn Welch authored 4 years ago and Peter Senna Tschudin committed 4 years ago

Move documents out of designs and into more suitable locations following
the layout guidelines.

Perform some minor edits to correct typos and remove unneeded titles.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

.gitattributes is used by many projects in their development workflows.
THis can, many a times, interfere with the Apertis package development
workflow. Thus document the fix for such cases.

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

Martyn Welch authored 4 years ago and Martyn Welch committed 4 years ago

An evaluation has been performed of the test cases to determine their
validity and value in respect to the current focus and direction of
Apertis. Add a document showing the analysis and recommendations reached as
a result of this evaluation.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Ritesh Raj Sarraf authored 4 years ago and Martyn Welch committed 4 years ago

The base-files package, depending on its branch name, generates the os
distribution specific attributes. Since those attributes expect a
certain set of infrastructure changes available (eg. new release's
docker images), this step is classified to be executed manually.

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Update the document to reflect the latest implementation status.

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Martyn Welch authored 4 years ago and Emanuele Aina committed 4 years ago

Add a basic description to the index page for each of the "official"
sections (as laid out inthe websites README.md). This provides visitors to
the site with some guidance as to what to expect to find in each section,
somewhere to point out to related polices (such as the release schedule and
flow from the releases section) and a way to add aliases (such as the
missing alias to Guides for the "Guidelines" section that was found on the
old wiki).

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Emanuele Aina authored 4 years ago and Frederic Danis committed 4 years ago

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

SabreLite v1.0 has a reversed switch position for SW1 for
normal and USB-OTG boot. Since it is very rare and old board
there is no need to provide the photo but it is useful to mention
about the difference.

Signed-off-by: Denis Pynkin <denis.pynkin@collabora.com>

Should be armhf architecture for SabreLite.

Signed-off-by: Denis Pynkin <denis.pynkin@collabora.com>

Andrej Shadura authored 4 years ago and Sjoerd Simons committed 4 years ago

Future changes to the licensing of some TLS implementations are
compounding an already uncertain licensing situation. Add a document
describing the situation; an analysis of options to rectify this and
our recommendations.

Signed-off-by: Andrej Shadura <andrew.shadura@collabora.co.uk>
Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>

This documents the invocation of the automation script for folding
changes. And also emphasizes that the final result should be validated
manually.

Signed-off-by: Ritesh Raj Sarraf <ritesh.sarraf@collabora.com>

Emanuele Aina authored 4 years ago and Martyn Welch committed 4 years ago

This document describes how we built images on Jenkins, but we have now
largely moved away from it in favor of GitLab CI/CD.

The README in the infrastructure/apertis-image-recipes> project
describes the current setup closer to the actual code.

Keep the document around since v2019 and v2020 are still officially on
Jenkins and old release notes still point here.

Signed-off-by: Emanuele Aina <emanuele.aina@collabora.com>