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

Following the tweaks to the pages the images need to be moved to their new
expected location under images.

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>

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

The pages in the site map are currently ordered by date. This doesn't make
much sense in the list. Order alphabetically instead to make it a bit
clearer.

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

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

Add the expectations for the utilisation of the various existing sections
to the website README.md to help guide contributors.

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>

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

We have enabled the generation of PDFs when appropriate using a custom
output type "pdf-in". When the PDF is being produced, add a link to the
page to alert readers to its existance.

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

Add the `lightweight` tag to run jobs on the GitLab runners set up for
jobs that do not need large amounts of resources (max 2GB of RAM) and do
not need privileged containers.

The former makes jobs cheaper because they user smaller VM instance
types, the latter improves latency as there's no strong need to spin
separate VMs to keep each job isolated and existing instances can be
re-used instead.

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>

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

The site menu is quite long. When we are in a section, scroll the menu to
the relevant section.

This is a bit hacky due to the navbar at the top and the way the theme is
constructed. In order to avoid issues with the scrolling distance being
incorrectly calculated (due to reflow of text as the side bar gets wider)
animate as a drop-down instead of appearing from the side.

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

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

We can change the logic subtly and reduce replication of properties.
Also set visibility to improve accessibility.

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

This reverts commit d7d0dfd9.

The patch was ineffective and thus being reverted to ensure we don't build
up cruft.

Signed-off-by: Martyn Welch <martyn.welch@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>

We have the Apertis Logo linked from the Debian census here:

  https://wiki.debian.org/Derivatives/Census/Apertis

This entry was added to the census when we were still using the wiki. As a
result it is linking to:

  https://wiki.apertis.org/mediawiki/images/2/27/Apertis-100.png

This no longer exists, it is redirected to:

  https://www.apertis.org/old-wiki/mediawiki/images/2/27/Apertis-100.png



The quickest solution is to ensure this image exists. We can look at
updating the census data as well, but that will probably take longer.

Signed-off-by: Martyn Welch <martyn.welch@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>

It has been communicated to us that the menu on the left hand side of the
designs.apertis.org site is missed when looking for documents on the
website. Implement a basic site menu in a sidebar to get feedback.

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