Skip to content

Commit 930c0a3

Browse files
SuyashParmarSuyash Parmar
SuyashParmar
and
Suyash Parmar
authored
Update the docs versioning (#1040)
* docs: release version 0.5 and configure latest versioning * Delete website/versioned_docs/version-0.5/.gitignore * Delete website/versioned_sidebars/version-0.5-sidebars.json * fix(website): populate version-0.5 docs to fix build * fix(ci): handle missing asf-site branch in deployment workflow * Delete website/versioned_docs/version-0.5/qumat-gap-analysis-for-pqc.md * Delete .github/workflows/website.yml * chore(website): remove version-0.5 docs content but keep config * revert: restore original website.yml workflow (no changes) * fix(website): update sync script to populate version-0.5 docs during build * feat(docs): add proper version 0.5 snapshot and update labels (PR review) * fix(docs): remove .gitignore from version-0.5 to allow committing docs --------- Co-authored-by: Suyash Parmar <suyashparmar@Suyashs-MacBook-Pro.local>
1 parent 65192d5 commit 930c0a3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+5067
-5
lines changed

‎website/docusaurus.config.ts‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import {themes as prismThemes} from 'prism-react-renderer';
2-
import type {Config} from '@docusaurus/types';
1+
import { themes as prismThemes } from 'prism-react-renderer';
2+
import type { Config } from '@docusaurus/types';
33
import type * as Preset from '@docusaurus/preset-classic';
44
import remarkMath from 'remark-math';
55
import rehypeKatex from 'rehype-katex';
@@ -46,10 +46,14 @@ const config: Config = {
4646
remarkPlugins: [remarkMath],
4747
rehypePlugins: [rehypeKatex],
4848
// Versioning configuration
49-
lastVersion: 'current',
49+
lastVersion: '0.5',
5050
versions: {
5151
current: {
52-
label: '0.5',
52+
label: 'next',
53+
path: 'next',
54+
},
55+
'0.5': {
56+
label: 'latest', // or '0.5' if preferred
5357
path: '',
5458
},
5559
'0.4': {

‎website/scripts/sync-docs.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ function parseFrontmatter(content) {
9797
let value = line.slice(colonIndex + 1).trim();
9898
// Remove quotes if present
9999
if ((value.startsWith('"') && value.endsWith('"')) ||
100-
(value.startsWith("'") && value.endsWith("'"))) {
100+
(value.startsWith("'") && value.endsWith("'"))) {
101101
value = value.slice(1, -1);
102102
}
103103
frontmatter[key] = value;

‎website/versioned_docs/version-0.5/about/how-to-contribute.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: How To Contribute
3+
sidebar_label: How To Contribute
4+
---
5+
6+
# How to contribute
7+
8+
*Contributing to an Apache project* is about more than just writing code --
9+
it's about doing what you can to make the project better. There are lots
10+
of ways to contribute!
11+
12+
<a name="HowToContribute-BeInvolved"></a>
13+
## Get Involved
14+
15+
Discussions at Apache happen on the mailing list. To get involved, you should join the [Mahout mailing lists](../community/mailing-lists). In particular:
16+
17+
* The **user list** (to help others)
18+
* The **development list** (to join discussions of changes) -- This is the best place
19+
to understand where the project is headed.
20+
* The **commit list** (to see changes as they are made)
21+
22+
Please keep discussions about Mahout on list so that everyone benefits.
23+
Emailing individual committers with questions about specific Mahout issues
24+
is discouraged. See [https://www.apache.org/theapacheway/](https://www.apache.org/theapacheway/)
25+
. Apache has a number of [email tips for contributors][1] as well.
26+
27+
<a name="HowToContribute-WhattoWorkOn?"></a>
28+
## What to Work On?
29+
30+
What do you like to work on? There are a ton of things in Mahout that we
31+
would love to have contributions for: documentation, performance improvements, better tests, etc.
32+
The best place to start is by looking into our [issue tracker](https://issues.apache.org/jira/browse/MAHOUT) and
33+
seeing what bugs have been reported and seeing if any look like you could
34+
take them on. Small, well written, well tested patches are a great way to
35+
get your feet wet. It could be something as simple as fixing a typo. The
36+
more important piece is you are showing you understand the necessary steps
37+
for making changes to the code. Mahout is a pretty big beast at this
38+
point, so changes, especially from non-committers, need to be evolutionary
39+
not revolutionary since it is often very difficult to evaluate the merits
40+
of a very large patch. Think small, at least to start!
41+
42+
Beyond JIRA, hang out on the dev@ mailing list. That's where we discuss
43+
what we are working on in the internals and where you can get a sense of
44+
where people are working.
45+
46+
Also, documentation is a great way to familiarize yourself with the code
47+
and is always a welcome addition to the codebase and this website. Feel free
48+
to contribute texts and tutorials! Committers will make sure they are added
49+
to this website, and we have a [guide for making website updates][2].
50+
We also have a [wide variety of books and slides][3] for learning more about
51+
machine learning algorithms.
52+
53+
If you are interested in working towards being a committer, general guidelines are available in the [Apache Community documentation](https://community.apache.org/contributors/).
54+
55+
<a name="HowToContribute-ContributingCode(Features,BigFixes,Tests,etc...)"></a>
56+
## Contributing Code (Features, Big Fixes, Tests, etc...)
57+
58+
This section identifies the ''optimal'' steps community member can take to
59+
submit a changes or additions to the Mahout code base. This can be new
60+
features, bug fixes optimizations of existing features, or tests of
61+
existing code to prove it works as advertised (and to make it more robust
62+
against possible future changes).
63+
64+
Please note that these are the "optimal" steps, and community members that
65+
don't have the time or resources to do everything outlined on this below
66+
should not be discouraged from submitting their ideas "as is" per "Yonik
67+
Seeley's (Solr committer) Law of Patches":
68+
69+
*A half-baked patch in Jira, with no documentation, no tests and no backwards compatibility is better than no patch at all.*
70+
71+
Just because you may not have the time to write unit tests, or cleanup
72+
backwards compatibility issues, or add documentation, doesn't mean other
73+
people don't. Putting your patch out there allows other people to try it
74+
and possibly improve it.
75+
76+
<a name="HowToContribute-Gettingthesourcecode"></a>
77+
## Getting the source code
78+
79+
First of all, you need to get the Mahout source code from [GitHub](https://github.com/apache/mahout). Most development is done on the "main" branch. The first step to making a contribution is to fork Mahout's main branch to your GitHub repository.
80+
81+
82+
<a name="HowToContribute-MakingChanges"></a>
83+
## Making Changes
84+
85+
Before you start, you should send a message to the [Mahout developer mailing list](../community/mailing-lists)
86+
(note: you have to subscribe before you can post), or file a ticket in our [issue tracker](https://issues.apache.org/jira/browse/MAHOUT).
87+
Describe your proposed changes and check that they fit in with what others are doing and have planned for the project. Be patient, it may take folks a while to understand your requirements.
88+
89+
1. Create a JIRA Issue in the [issue tracker](https://issues.apache.org/jira/browse/MAHOUT) (if one does not already exist)
90+
2. Pull the code from your GitHub repository
91+
3. Ensure that you are working with the latest code from the [apache/mahout](https://github.com/apache/mahout) main branch.
92+
3. Modify the source code and add some (very) nice features.
93+
- Be sure to adhere to the following points:
94+
- All public classes and methods should have informative Javadoc
95+
comments.
96+
- Code should be formatted according to standard
97+
[Java coding conventions](http://www.oracle.com/technetwork/java/codeconventions-150003.pdf),
98+
with two exceptions:
99+
- indent two spaces per level, not four.
100+
- lines can be 120 characters, not 80.
101+
- Contributions should pass existing unit tests.
102+
- New unit tests should be provided to demonstrate bugs and fixes.
103+
4. Commit the changes to your local repository.
104+
4. Push the code back up to your GitHub repository.
105+
5. Create a [Pull Request](https://help.github.com/articles/creating-a-pull-request) to the to apache/mahout repository on Github.
106+
- Include the corresponding JIRA Issue number and description in the title of the pull request:
107+
- ie. MAHOUT-xxxx: < JIRA-Issue-Description >
108+
6. Committers and other members of the Mahout community can then comment on the Pull Request. Be sure to watch for comments, respond and make any necessary changes.
109+
110+
Please be patient. Committers are busy people too. If no one responds to your Pull Request after a few days, please make friendly reminders on the mailing list. Please
111+
incorporate other's suggestions into into your changes if you think they're reasonable. Finally, remember that even changes that are not committed are useful to the community.
112+
113+
<a name="HowToContribute-UnitTests"></a>
114+
#### Unit Tests
115+
116+
Please make sure that all unit tests succeed before creating your Pull Request.
117+
118+
Run *mvn clean test*, if you see *BUILD SUCCESSFUL* after the tests have finished, all is ok, but if you see *BUILD FAILED*,
119+
please carefully read the errors messages and check your code.
120+
121+
#### Do's and Don'ts
122+
123+
Please do not:
124+
125+
* reformat code unrelated to the bug being fixed: formatting changes should
126+
be done in separate issues.
127+
* comment out code that is now obsolete: just remove it.
128+
* insert comments around each change, marking the change: folks can use
129+
subversion to figure out what's changed and by whom.
130+
* make things public which are not required by end users.
131+
132+
Please do:
133+
134+
* try to adhere to the coding style of files you edit;
135+
* comment code whose function or rationale is not obvious;
136+
* update documentation (e.g., ''package.html'' files, the website, etc.)
137+
138+
139+
<a name="HowToContribute-Review/ImproveExistingPatches"></a>
140+
## Review/Improve Existing Pull Requests
141+
142+
If there's a JIRA issue that already has a Pull Request with changes that you think are really good, and works well for you -- please add a comment saying so. If there's room
143+
for improvement (more tests, better javadocs, etc...) then make the changes on your GitHub branch and add a comment about them. If a lot of people review a Pull Request and give it a
144+
thumbs up, that's a good sign for committers when deciding if it's worth spending time to review it -- and if other people have already put in
145+
effort to improve the docs/tests for an issue, that helps even more.
146+
147+
For more information see [Handling GitHub PRs](http://mahout.apache.org/documentation/developers/github).
148+
149+
150+
[1]: http://www.apache.org/dev/contrib-email-tips
151+
[2]: http://mahout.apache.org/documentation/developers/how-to-update-the-website.html
152+
[3]: http://mahout.apache.org/general/books-tutorials-and-talks.html

‎website/versioned_docs/version-0.5/adr/001-jekyll-to-docusaurus-migration.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: "ADR-001: Jekyll to Docusaurus Migration"
3+
sidebar_label: "ADR-001: Jekyll to Docusaurus"
4+
---
5+
6+
<!--
7+
Licensed to the Apache Software Foundation (ASF) under one or more
8+
contributor license agreements. See the NOTICE file distributed with
9+
this work for additional information regarding copyright ownership.
10+
The ASF licenses this file to You under the Apache License, Version 2.0
11+
(the "License"); you may not use this file except in compliance with
12+
the License. You may obtain a copy of the License at
13+
14+
http://www.apache.org/licenses/LICENSE-2.0
15+
16+
Unless required by applicable law or agreed to in writing, software
17+
distributed under the License is distributed on an "AS IS" BASIS,
18+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19+
See the License for the specific language governing permissions and
20+
limitations under the License.
21+
-->
22+
23+
# ADR-001: Jekyll to Docusaurus Migration
24+
25+
## Status
26+
27+
Accepted
28+
29+
## Date
30+
31+
2026-01-22
32+
33+
## Context
34+
35+
The Apache Mahout website was built using Jekyll 4.3.2 with Bootstrap 5, MathJax 3 for math rendering, and Kramdown for Markdown processing. As the project evolved with the introduction of Qumat (quantum computing capabilities), we needed to evaluate our documentation infrastructure.
36+
37+
### Problems with Jekyll
38+
39+
1. **Ruby ecosystem maintenance** - Managing Ruby/Bundler dependencies and versions adds complexity
40+
2. **Limited interactivity** - Jekyll is purely static; no React components for dynamic content
41+
3. **Documentation versioning** - No built-in support for multi-version documentation
42+
4. **Developer experience** - Hot reload and local development workflows are slower
43+
5. **Documentation sync** - No standard pattern for syncing `/docs` with website content
44+
45+
### Requirements
46+
47+
- Documentation versioning for Qumat releases (0.4, 0.5, etc.)
48+
- Math/LaTeX support for quantum computing documentation
49+
- `/docs` directory as source of truth for documentation
50+
- Fast local development with hot reload
51+
- React components for enhanced interactivity
52+
- Modern JavaScript tooling (Node.js ecosystem)
53+
54+
## Decision
55+
56+
Migrate from Jekyll to **Docusaurus 3.x** with the following configuration:
57+
58+
### Technology Choices
59+
60+
| Component | Decision | Rationale |
61+
|-----------|----------|-----------|
62+
| Framework | Docusaurus 3.x | Active development, React-based, built-in versioning |
63+
| Math rendering | KaTeX | Faster than MathJax, lighter bundle size, covers 95%+ use cases |
64+
| Migration approach | New directory (`website-new/`) | Safe migration, can keep Jekyll during transition |
65+
| Versioning | Enabled from start | Supports Qumat release cycle |
66+
67+
### Architecture
68+
69+
```
70+
website-new/
71+
├── docusaurus.config.ts # Main configuration
72+
├── sidebars.ts # Sidebar navigation
73+
├── package.json
74+
├── scripts/
75+
│ └── sync-docs.js # Syncs /docs → website-new/docs
76+
├── docs/ # Current version (synced from /docs)
77+
├── versioned_docs/ # Previous versions (snapshots)
78+
│ └── version-0.4/
79+
├── versions.json # Version manifest
80+
├── blog/ # Migrated from Jekyll _posts
81+
├── src/
82+
│ ├── components/ # React components
83+
│ ├── css/custom.css # Theme customizations
84+
│ └── pages/index.tsx # Custom homepage
85+
└── static/ # Images and assets
86+
```
87+
88+
### Documentation Sync Workflow
89+
90+
The `/docs` directory at the repository root is the source of truth. A sync script copies documentation to the website at build time:
91+
92+
1. `npm run sync` - Copies `/docs` and `/qdp/docs` to `website-new/docs/`
93+
2. Transforms frontmatter as needed
94+
3. Runs automatically before `npm run build` and `npm run start`
95+
96+
This pattern allows:
97+
- Documentation to live alongside code
98+
- Website to always reflect latest `/docs`
99+
- Version snapshots to preserve historical documentation
100+
101+
### Versioning Strategy
102+
103+
- `current` (0.5-dev): Active development, synced from `/docs`
104+
- `0.4`: First stable snapshot, frozen documentation
105+
106+
To create a new version:
107+
```bash
108+
npm run docusaurus docs:version X.Y
109+
```
110+
111+
## Consequences
112+
113+
### Positive
114+
115+
1. **Versioned documentation** - Users can view docs for their specific Qumat version
116+
2. **Faster builds** - Node.js build pipeline is faster than Jekyll
117+
3. **React components** - Can add interactive examples, code playgrounds
118+
4. **Better DX** - Fast hot reload, TypeScript support, modern tooling
119+
5. **KaTeX performance** - Math rendering is 10x faster than MathJax
120+
6. **Active community** - Docusaurus has strong Meta backing and active maintenance
121+
122+
### Negative
123+
124+
1. **Learning curve** - Team needs to learn React/Docusaurus patterns
125+
2. **Migration effort** - One-time cost to migrate all content
126+
3. **KaTeX limitations** - Some advanced MathJax features may not work (rare edge cases)
127+
128+
### Neutral
129+
130+
1. **Bundle size** - Slightly larger JavaScript bundle, but better caching
131+
2. **CI/CD changes** - GitHub Actions updated from Ruby to Node.js
132+
133+
## Implementation Notes
134+
135+
### Key Files Changed
136+
137+
- `.github/workflows/website.yml` - Now uses Node.js instead of Ruby
138+
- `website-new/docusaurus.config.ts` - Main Docusaurus configuration
139+
- `website-new/scripts/sync-docs.js` - Documentation sync script
140+
- `website-new/src/components/WaveAnimation/` - Ported hero animation
141+
142+
### Redirect Strategy
143+
144+
Client-side redirects handle old Jekyll URLs:
145+
- `/news.html` → `/blog`
146+
147+
Additional redirects can be added to `docusaurus.config.ts` as needed.
148+
149+
## References
150+
151+
- [Docusaurus documentation](https://docusaurus.io/)
152+
- [KaTeX supported functions](https://katex.org/docs/supported.html)
153+
- [GitHub discussion](https://github.com/apache/mahout/discussions/) (original proposal)

0 commit comments

Comments
 (0)