recipes/docs_builder.py

# Copyright 2020 The Pigweed Authors
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
# the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations under
# the License.
"""Generate docs using GN/Ninja and upload to GCS."""

from PB.go.chromium.org.luci.buildbucket.proto import common
from PB.recipes.pigweed.docs_builder import InputProperties
from PB.recipe_engine import result

DEPS = [
    'fuchsia/buildbucket_util',
    'fuchsia/gerrit',
    'fuchsia/gsutil',
    'pigweed/build',
    'pigweed/checkout',
    'pigweed/environment',
    'pigweed/pw_presubmit',
    'recipe_engine/file',
    'recipe_engine/json',
    'recipe_engine/properties',
    'recipe_engine/swarming',
]

PROPERTIES = InputProperties


def RunSteps(api, props):  # pylint: disable=invalid-name
    checkout = api.checkout(props.checkout_options)
    env = api.environment.init(checkout, props.environment_options)

    if props.HasField('build_options'):
        build = api.build.create(checkout.root, props.build_options)
        with env():
            api.build(build)
        out_dir = build.root
    elif props.HasField('pw_presubmit_options'):
        with env():
            presubmit = api.pw_presubmit.init(
                checkout.root, props.pw_presubmit_options
            )
            assert len(presubmit.steps) == 1
            for step in presubmit.steps:
                api.pw_presubmit.run(ctx=presubmit, step=step, env=env)
                out_dir = step.dir
    else:
        assert False  # pragma: no cover

    html_path = props.html_path or 'docs/gen/docs/html'
    html = out_dir.join(*html_path.split('/'))

    if props.dry_run:
        path = f'testing/swarming-{api.swarming.task_id}/{checkout.revision()}'
    elif api.buildbucket_util.is_tryjob:
        path = api.buildbucket_util.id
    else:
        path = checkout.revision()

    bucket = props.bucket or 'pigweed-docs'
    api.gsutil.upload(
        bucket=bucket, src=html, dst=path, recursive=True, multithreaded=True,
    )

    # If in a tryjob there's no need to even fetch metadata.
    if not api.buildbucket_util.is_tryjob:
        # Getting gerrit details even if this is a dry run so testing will show
        # if it would have worked.
        change = api.gerrit.change_details(
            'get change details',
            change_id=str(checkout.revision()),
            host=checkout.gerrit_host(),
            max_attempts=5,
            timeout=30,
            test_data=api.json.test_api.output({'branch': 'main'}),
        ).json.output

        if change['branch'] in ('master', 'main') and not props.dry_run:
            head = checkout.root.join('HEAD')
            api.file.write_text('write HEAD', head, checkout.revision())
            api.gsutil.upload(bucket=bucket, src=head, dst='HEAD')

            api.gsutil.rsync(
                bucket=bucket,
                src=html,
                dst='latest',
                recursive=True,
                multithreaded=True,
            )

    link_fmt = props.link or 'https://pigweed.dev/?rev={}'
    link = link_fmt.format(path)

    return result.RawResult(
        summary_markdown=f'Docs available at {link}.', status=common.SUCCESS,
    )


def GenTests(api):  # pylint: disable=invalid-name
    def properties(**kwargs):
        props = InputProperties(**kwargs)
        props.checkout_options.CopyFrom(api.checkout.git_options())
        return api.properties(props)

    yield (
        api.test('docs-dry_run-build')
        + properties(
            dry_run=True,
            build_options=api.build.options(ninja_targets=['target']),
        )
    )

    yield (
        api.test('docs-postsubmit')
        + properties(
            dry_run=False,
            pw_presubmit_options=api.pw_presubmit.options(step=['step']),
        )
    )

    yield (
        api.test('docs-presubmit')
        + api.checkout.try_test_data()
        + properties(
            dry_run=False,
            pw_presubmit_options=api.pw_presubmit.options(step=['step']),
        )
    )