entrypoint.py

#!/usr/bin/python3
# pylint: disable=C0103
# pylint: disable=C0114

import json
import os
import os.path
import shutil
import sys

import in_place
import yaml

# Output strings for coloring

ENDC = '\033[0m'
ERROR = '\033[31m'
INFO = '\033[34m'
NOTICE = '\033[33m'

library_name = os.environ['INPUT_LIBRARY_NAME']
docs_build_dir = os.environ['INPUT_DOCS_BUILD_DIR']

#
# make the documentation
#

print(INFO + "Running 'make docs'." + ENDC)
rslt = os.system('make docs')
if rslt != 0:
    print(ERROR + "'make docs' failed." + ENDC)
    sys.exit(1)

mkdocs_yml_file = os.path.join(docs_build_dir, 'mkdocs.yml')
docs_dir = os.path.join(docs_build_dir, 'docs')
index_file = os.path.join(docs_dir, 'index.md')
source_dir = os.path.join(docs_dir, 'src')

#
# remove any docs that aren't part of this library
# store information about removed entries so we can fix up links to them later
#

print(INFO + "Removing 'other docs'." + ENDC)
removed_docs = []
for f in os.listdir(docs_dir):
    if f in ('assets', 'src', 'index.md'):
        continue

    if not f.startswith(library_name + '-'):
        p = os.path.join(docs_dir, f)
        if os.path.isfile(p):
            os.remove(p)
        else:
            shutil.rmtree(p)
        removed_docs.append(f)

#
# remove any source code that isn't part of this library
#

print(INFO + "Removing 'other sources'." + ENDC)
for f in os.listdir(source_dir):
    if f != library_name:
        p = os.path.join(source_dir, f)
        if os.path.isfile(p):
            os.remove(p)
        else:
            shutil.rmtree(p)

#
# - trim mkdocs.yml down to entries for our library
#   record those packages for later reference
#

print(INFO + "Trimming mkdocs.yml." + ENDC)
mkdocs_yml = {}
packages = []
with open(mkdocs_yml_file, encoding="utf8") as infile:
    mkdocs_yml = yaml.load(infile, Loader=yaml.FullLoader)
    nav = mkdocs_yml['nav']

    new_nav = []
    library_package_key = 'package ' + library_name
    library_subpackage_key = 'package ' + library_name + '/'
    for entry in nav:
        # there's only 1 entry but we don't know what it is because
        # well that's how the yaml package represents this thing should be a
        # 2-element tuple or list
        for k in entry.keys():
            if k == library_name:
                # library index entry. keep it.
                new_nav.append(entry)

            if k == library_package_key \
              or k.startswith(library_subpackage_key):
                # package entry. keep it.
                # record the package name for later usage
                new_nav.append(entry)
                # entry will look like one of:
                # package semver
                # package semver/subpackage
                packages.append(k[8:])

    mkdocs_yml['nav'] = new_nav

# add a site url to fix some /asset links
# without this, the 404 page will be broken
mkdocs_yml['site_url'] = os.environ['INPUT_SITE_URL']

with open(mkdocs_yml_file, 'w', encoding="utf8") as outfile:
    yaml.dump(mkdocs_yml, outfile)

#
# trim docs/index.md down to entries for our library
#

print(INFO + "Trimming index.md." + ENDC)
with in_place.InPlace(index_file) as fp:
    for line in fp:
        if not line.startswith('*'):
            fp.write(line)
        else:
            for p in packages:
                if line.startswith('* [' + p + ']'):
                    fp.write(line)

#
# `make docs` at the start will have pulled down any needed dependencies that
# we might have. Here we are going to reach into the _corral directory to find
# the `corral.json` for any dependencies and get:
# - the package names
# - the location of the documentation_url
#
# This should eventually be incorporated into `corral` as a command
# or something similar. In the meantime, we are doing "by hand" in this
# action as we work out how to accomplish everything that we want to.
#
# This could grab info about "extra" packages as there is on guarantee that a
# dependency that was removed isn't still in _corral directory assuming that
# this code was used outside of the context of this action that starts from a
# clean-slate. That's not an edge condition to worry about at this time.
#
# packages provided are listed in `corral.json` in an array with the key
# `packages`. Every package needs to be listed including those that are
# "subpackages" so for example, we have package listings for `semver`,
# `semver/constraint`, and `semver/version`.
#
# The documentation_url for a given package is located in the `info` object
# in the `documentation_url` field.
#

documentation_urls = {}

if os.path.isdir("_corral"):
    dependencies_dirs = os.listdir("_corral")
    for dd in dependencies_dirs:
        corral_file = "/".join(["_corral", dd, "corral.json"])
        if not os.path.isfile(corral_file):
            print(NOTICE + "No corral.json in " + dd + "." + ENDC)
            continue

        with open(corral_file, 'r', encoding="utf8") as corral_fd:
            corral_data = json.load(corral_fd)
            bundle_documentation_url = ""
            try:
                bundle_documentation_url = corral_data['info']['documentation_url']
            except KeyError as e:
                print(NOTICE + "No documentation_url in " + corral_file + "." \
                  + ENDC)

            try:
                packages = corral_data['packages']
                for p in packages:
                    documentation_urls[p] = bundle_documentation_url
            except KeyError as e:
                print(NOTICE + "No packages in " + corral_file + "." \
                  + ENDC)

#
# Go through the markdown belonging to our package and replace missing entries
# with links to their external sites.
#

print(INFO + "Fixing links to code outside of our package." + ENDC)
for f in os.listdir(docs_dir):
    if f in ('assets', 'src'):
        continue

    p = os.path.join(docs_dir, f)
    print(INFO + "Fixing links in " + str(p) + "." + ENDC)
    with in_place.InPlace(p) as fp:
        for line in fp:
            for removed in removed_docs:
                if removed in line:
                    print(INFO + "Replacing link for " + removed + "." + ENDC)

                    # get the package name
                    s = removed.replace('.md', '')
                    s = s.split('-')
                    if len(s) > 1:
                        del s[-1]
                    package_name = '/'.join(s)

                    # if unknown package, we'll use the standard library
                    external_url = documentation_urls.get(package_name, \
                      'https://stdlib.ponylang.io/')

                    # as the external url is input from users, it might not
                    # include a trailing slash. if not, generated urls will
                    # be broken.
                    # there's far more validation we could do here, but in
                    # terms of helping out a non-malicious user, this is the
                    # minimum
                    if not external_url.endswith('/'):
                        external_url += '/'

                    as_html = removed.replace('.md', '')
                    link = external_url + as_html + "/"
                    line = line.replace(removed, link)

            fp.write(line)

#
# run mkdocs to actually build the content
#

print(INFO + "Running 'mkdocs build'." + ENDC)
os.chdir(docs_build_dir)
rslt = os.system('mkdocs build')
if rslt != 0:
    print(ERROR + "'mkdocs build' failed." + ENDC)
    sys.exit(1)