Copilot commented on code in PR #1040:
URL: https://github.com/apache/mahout/pull/1040#discussion_r2791593850
##########
website/versions.json:
##########
@@ -1,3 +1,4 @@
[
+ "0.5",
Review Comment:
Adding "0.5" to versions.json will make Docusaurus treat 0.5 as a version
that must have a corresponding snapshot (e.g.,
`website/versioned_docs/version-0.5/` and typically
`website/versioned_sidebars/version-0.5-sidebars.json`). Those artifacts are
not present in the repo (only 0.4 exists), so the site build is likely to fail
or the version dropdown will be inconsistent. Consider generating the 0.5
snapshot via `docusaurus docs:version 0.5` and committing the generated
versioned docs/sidebars, or revert to `lastVersion: 'current'` if 0.5 should
remain the current docs instead of a versioned snapshot.
```suggestion
```
##########
website/scripts/sync-docs.js:
##########
@@ -256,6 +257,14 @@ function main() {
console.log('\nSyncing documentation from /docs...');
const docsStats = syncDirectory(SOURCE_DIR, DEST_DIR);
+ // Sync versioned_docs (version 0.5) to fix build without committing files
+ console.log(`\nVersioned Docs Destination: ${VERSIONED_DOCS_DIR}\n`);
+ console.log('Cleaning versioned docs destination...');
+ cleanDestination(VERSIONED_DOCS_DIR);
+
+ console.log('\nSyncing documentation to versioned_docs/version-0.5...');
+ syncDirectory(SOURCE_DIR, VERSIONED_DOCS_DIR);
+
Review Comment:
Syncing `/docs` into `versioned_docs/version-0.5` on every build means the
“0.5” docs are no longer a frozen snapshot; they will silently track whatever
is in `/docs` at build time, which defeats Docusaurus versioning and can make
historical docs inaccurate. If 0.5 is intended to be a released snapshot,
generate it once with `docusaurus docs:version 0.5` and commit the generated
`versioned_docs` and `versioned_sidebars` artifacts instead of overwriting them
during `npm run sync`.
```suggestion
// NOTE: Versioned docs (e.g., version-0.5) should be created and managed
// via `docusaurus docs:version` and committed to the repository as
// frozen snapshots. We intentionally do not sync SOURCE_DIR into
// versioned_docs here to avoid mutating released documentation.
```
##########
website/scripts/sync-docs.js:
##########
@@ -20,6 +20,7 @@ const path = require('path');
// Configuration
const SOURCE_DIR = path.resolve(__dirname, '../../docs');
const DEST_DIR = path.resolve(__dirname, '../docs');
+const VERSIONED_DOCS_DIR = path.resolve(__dirname,
'../versioned_docs/version-0.5');
Review Comment:
`VERSIONED_DOCS_DIR` is hard-coded to `version-0.5`. This will require code
changes for every future release and makes the sync behavior easy to forget.
Prefer deriving the target version from `versions.json`/Docusaurus config or
accepting the version as a CLI arg/env var (and failing fast if it doesn’t
exist).
```suggestion
const DOCS_VERSION = process.env.DOCS_VERSION || process.argv[2];
if (!DOCS_VERSION) {
console.error('Error: Documentation version not specified. Set
DOCS_VERSION env var or pass as first CLI argument.');
process.exit(1);
}
const VERSIONED_DOCS_DIR = path.resolve(__dirname,
`../versioned_docs/version-${DOCS_VERSION}`);
```
##########
website/docusaurus.config.ts:
##########
@@ -46,9 +46,13 @@ const config: Config = {
remarkPlugins: [remarkMath],
rehypePlugins: [rehypeKatex],
// Versioning configuration
- lastVersion: 'current',
+ lastVersion: '0.5',
versions: {
current: {
+ label: 'latest',
+ path: 'next',
+ },
+ '0.5': {
label: '0.5',
Review Comment:
With `lastVersion: '0.5'`, the `current` version becomes the
“next/unreleased” docs at `/docs/next`. Labeling `current` as `latest` is
misleading in the version dropdown (it suggests it’s the stable release).
Consider renaming the `current` label to something like `next`/`dev` and
reserving `latest` (if desired) for the `0.5` entry.
```suggestion
label: 'next',
path: 'next',
},
'0.5': {
label: 'latest (0.5)',
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
