T6572: Move developer docs to main website
- Oct 19, 2020
-
-
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> -
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>a7232521 -
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>7b0645c0 -
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>539a720c -
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>14ac8ffe -
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>cd14862c -
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>96826db7 -
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>597af7c0 -
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>749945ba -
A quick first pass to clean up the developer index page. Signed-off-by:Martyn Welch <martyn.welch@collabora.com>056173c6 -
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>156f2465 -
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>02faa07f -
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>e156cd2c -
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 = ("" % 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>3bb17562 -
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>453977a1 -
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>286d5488
-
