chore: publish docs to website #218
Conversation
|
CC @nealrichardson I know you wanted to have |
|
CC @kou does this look OK? Maybe this should instead go under |
|
Updated. |
|
Why do we want to generate How about putting the latest documents to https://arrow.apache.org/adbc/ and the dev documents to https://arrow.apache.org/adbc/dev/ like https://arrow.apache.org/docs/ and https://arrow.apache.org/docs/dev/ ? BTW, we need to copy |
I was thinking about having some sort of (brief) landing page, but it is redundant. (Or maybe a redirect, or a version selector.)
I wanted to have versioned documentation from the start, so it seems weird to me to have them nested like that. (I still need to look at different approaches to that, but something like https://github.com/steinwurf/versjon assumes each version falls in its own subdirectory.) But consistency probably matters more.
Ah, thank you. |
Ah, it makes sense.
I agree with you. FYI: I like the following URLs:
|
|
We can use apache/arrow-adbc for the "redirect" approach because we just need to put a simple HTML. We don't need to use the same design in https://arrow.apache.org/ for the approach. |
|
Cool. I've reverted it to deploy to adbc/. Also, I added https://github.com/steinwurf/versjon which generates the index.html with a redirect for us. It also embeds a version switcher into the docs, and generates a |
|
Ah, versjon is not idempotent, hmm. |
|
I'll take a look at embedding it ourselves |
|
Ok…added a homegrown version switcher. It embeds a reference to a JavaScript file in the generated docs. The JavaScript file will sit in Details// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you 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
//
// http://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.
window.addEventListener("DOMContentLoaded", () => {
// Injected by template
window.fetch(versionListingPath)
.then((r) => r.text())
.then((text) => {
const root = document.querySelector("#version-switcher ul");
const versions = text
.trim()
.split(/\n/g)
.map((version) => {
return version.split(/;/);
});
const versionRegex = /^([0-9]+)\.([0-9]+)\.([0-9]+)(.*)$/;
versions.sort((x, y) => {
const lhs = x[1].match(versionRegex);
const rhs = y[1].match(versionRegex);
if (lhs === null && rhs === null) {
return x[1].localeCompare(y[1]);
}
if (lhs === null) return 1;
if (rhs === null) return -1;
// Major
const lhsMajor = parseInt(lhs[1], 10);
const rhsMajor = parseInt(rhs[1], 10);
if (lhsMajor < rhsMajor) {
return -1;
} else if (lhsMajor > rhsMajor) {
return 1;
}
const lhsMinor = parseInt(lhs[2], 10);
const rhsMinor = parseInt(rhs[2], 10);
if (lhsMinor < rhsMinor) {
return -1;
} else if (lhsMinor > rhsMinor) {
return 1;
}
const lhsPatch = parseInt(lhs[3], 10);
const rhsPatch = parseInt(rhs[3], 10);
if (lhsPatch < rhsPatch) {
return -1;
} else if (lhsPatch > rhsPatch) {
return 1;
}
return lhs[4].localeCompare(rhs[4]);
});
versions.forEach((version) => {
const el = document.createElement("a");
el.setAttribute("href", versionsRoot + "/" + version[0]);
el.innerText = version[1];
if (version[1] === currentVersion) {
el.classList.toggle("active");
}
const li = document.createElement("li");
li.appendChild(el);
root.appendChild(li);
});
});
});It just populates a list embedded in the docs. The generated docs style the list. The versions are pulled from a text file that we can generate in CI. |
|
It looks like this:
(screenshot doesn't capture it, but it scrolls) |
|
Unlike versjon, because it doesn't modify the docs HTML, it is idempotent. We can update the switcher in all docs just by updating the text file and/or JavaScript file. (We could save a round-trip with some more acrobatics, by templating the JavaScript file with the contents of the text file, but we can always do that later without having to regenerate docs.) |
|
Demo here: https://github.com/lidavidm/arrow-adbc/tree/asf-site (check out the branch and run And then in the release PR, I can have the action generate an |
|
Also updated that branch with the results of pushing a tag (which also generated index.html and latest/), though the |
How about maintaining it in the main branch and just copying it to the asf-site branch on publish? |
|
Ok! In that case I'll also move this Bash code out into actual scripts |
|
Updated!
Since I switched from |
|
Demo here: https://github.com/lidavidm/arrow-adbc/tree/asf-site Testing out the tag workflow here: https://github.com/lidavidm/arrow-adbc/actions/runs/3705059422 |
|
|
|
And #246 to prepare for deployment |
|
Thanks so much for your help! |
Remove the old 'dev' directory since #218 will change the deployment; add asf.yaml so this can be deployed.
|
It works! https://arrow.apache.org/adbc/ |
2 participants
No description provided.