aip-dev / site-generator Goto Github PK

In the current AIP-193 Markdown we have:

- For how to retry errors in client libraries, see [AIP-4221][].

The site generator creates a link for that to https://google.aip.dev/client-libraries/4221.md, whereas it should be https://google.aip.dev/client-libraries/4221 (no .md)

This can be fixed by making the link explicit, but if implicit links don't work then there's no point in having them.

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore: Update dependency flask to v2.2.5 [SECURITY]
• chore: Update dependency jinja2 to v3.1.3 [SECURITY]
• chore: Update dependency werkzeug to v2.3.8 [SECURITY]
• chore: Update dependency pymdown-extensions to v10 [SECURITY]
• chore: Update all (click, markdown, markupsafe, pygments, python, pyyaml, types-Markdown, types-PyYAML)
• chore: Update actions/checkout action to v4
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

hello! i am trying to get started with setting up my own AIP infrastructure. i started with the site-generator because it seemed like the logical place to start: set up the machinery, and then worry about feeding in some things to publish. the current README does not really help with how to get the thing up and running, so i am proposing to add this information.

sudo apt-get install python3-venv

When running python setup.py install, two directories, build and dist are created. Ignore them.

The logo in the top-left of the site currently comes from the site generator repo. It'd be great if the logo could come from the content repo instead (e.g. google.aip.dev). For example, maybe the presence of a logo.svg in that repo could override the default Google logo. @shwoodard

For example, look at the latest change to aip-162: aip-dev/google.aip.dev@e487231

In that change the author updated the updated field on line 3 of 0162.md

But, the had no impact on the date displayed in the generated HTML.

It looks like the logic of the update property in aip.py is to look for index 0 of the changelog and fall back to the created date if there isn't a changelog.

Perhaps the order of the changelog entries is upside down? Because, the author also updated the changelong in the same change and it still looks like the logic fell back to the created time.

AIPs now support versions: https://google.aip.dev/3.

the site-generator should support displaying these versions. e.g. via a drop-down.

I think the text here should be "API Improvement Proposals".

After migrating our AIPs to the new site generator, I immediately got a an error when trying to go to the main aip index (/general). The cause for the error is that the index page general.md -- because it ends with .md is being viewed as a AIP instead of the new scope.yaml that appears to define the index pages now.

Recognizing that there needs to be a migration the aip_index files to the new scope.yaml files, and recognizing that we might be the only consumer that needs to go through this migration process right now, I feel that we should maintain support for the old aip_index format as a matter of backwards compatability.

My primary motivation for this is that in addition to our core aip_index files, we also have three code blocks with separate code owners. For me to do the migration from aip_index to scope.yaml I would have to make the changes for them, and then wait until the volunteers from the core AIP editors and the three sub group owners can approve the changes before I can merge.

I would prefer to upgrade the core AIPs, and have them be an example to the sub groups who can upgrade to the new format at their leisure, recognizing that they do not get the benefits of the upgraded format (such as extension) until they upgrade to that format.

Additionally, I think this would just be a good best practice going forward, for the core infrastructure to support one or two previous versions of the AIP structure/format. This would allow sub-orgs and AIP maintainers a bit more flexibility when doing upgrades.

Update to new versions of dependencies.

The google.aip.dev repo licenses its AIP content under the Creative Commons Attribution 4.0 License. This means that anyone forking the AIPs has to include a notice on just about every page along the lines of "This page contains content that was modified and/or reproduced from work created or shared by Google and used according to the terms in the Creative Commons Attribution 4.0 License."

The simplest way to do this, currently, is to fork the site generator and modify the site footer to add a generic notice like the one above. A better way to do this, not requiring a site generator fork (e.g. a footer.yml in google.aip.dev), would be great.

Example wording would also be great, so that forkers don't have to consult their companies' legal departments.

See issue title.

There are a few Google-specific hard-coded things in the site generator; these make it necessary to fork the site generator in order to adopt AIPs outside of Google:

• "Google's API design decisions" in the welcome section of the main page.
• Google Analytics tracking stuff presumably specific to Google.
• The logo (mentioned here for completeness; I already filed #65 about this)

I'm not sure this is exhaustive, but it's what I've identified so far.