Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add release process for versioned docs. #6

Merged
merged 3 commits into from
Aug 28, 2023
Merged

Add release process for versioned docs. #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f37667f
Add release process for versioned docs.
bgravenorst Jul 31, 2023
7cc1097
fusing the version docs in the versions page
joshuafernandes Jul 31, 2023
f818537
Minor updates.
bgravenorst Aug 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/configure/search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ the conditions as long as the docs are open source.
This page contains instructions for configuring Algolia for both [open-source](#docs-and-source-code-are-open-source)
and [closed-source](#source-code-is-not-open-source) projects.

## Docs and source code are open source
## For an open source codebase

Follow these steps to configure Algolia in your project:

Expand Down Expand Up @@ -50,7 +50,7 @@ Follow these steps to configure Algolia in your project:
Edit the `docs` index in the file to match your repository's index in Algolia.
This workflow runs in the background and populates the index that Algolia uses to search.

## Source code is not open source
## For a close source code base

If your project doesn't satisfy the [Algolia checklist](https://docsearch.algolia.com/docs/who-can-apply/),
then you can't use Algolia for free.
Expand Down
149 changes: 141 additions & 8 deletions docs/configure/versioning/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,28 +3,161 @@ description: Support and manage multiple documentation versions.
sidebar_position: 1
---

# Configure versioning
# Configure and use versioning

Docusaurus can manage multiple versions of your documentation.
See the [Docusaurus versioning documentation](https://docusaurus.io/docs/next/versioning) for
detailed context and instructions on managing versions.

## Create a docs version
The following instructions are for documentation that uses n versions that can be accessed like so:

| Path | Version | URL |
|:----------------------------------- |:------------- |:-------------------|
|versioned_docs/version-0.x/hello.md | 0.x | /0.x/hello |
|versioned_docs/version-1.0/hello.md | 1.0 (latest) | /hello |
|docs/hello.md | development | /development/hello |

:::info
Please note that unlike Read the Docs (RTD) that versions by tags on the code base, in Docusaurus,
every version in history is kept in the `versioned_docs` folder, so the onus is on you to remove
older versions when required
:::

Docusaurus nomenclature is slightly different to what we use. In docusaurus, all actual versions
are referred to by name and are sub folders in `versioned_docs`; and the next version is therefore called
`next` (the next version). In Consensys we follow the same for the `versioned_docs` but use the
term `development` instead, and this can be configured in docusaurus.config.js like so, where
the `current` version is given a `label` and `path` attribute.

```js
...
routeBasePath: "/",
path: "./docs",
includeCurrentVersion: true,
lastVersion: "1.0",
versions: {
//defaults to the ./docs folder
// using 'development' instead of 'next' as path
current: {
label: "development",
path: "development",
},
//the last stable release in the versioned_docs/version-stable
"1.0": {
label: "1.0",
},
"0.x": {
label: "0.x",
},
},
...
```

## Release a new docs version

### 1. Create a new version of the documentation:

Release version 1.0 of your docs using the following command:
In the following steps, we'll release the `1.0` version of the documentation (`./docs`) as an example.

<!--tabs-->

# Syntax

```bash
npm run docusaurus docs:version <VERSION-NUMBER>
```

This command:

- Copies the full `docs/` directory into a new `version-<VERSION-NUMBER>` directory in the `versioned_docs` directory.
- Creates a new `versioned_sidebars/version-<VERSION-NUMBER>-sidebars.json` file.
- Appends the new version number to the `versions.json` file.

# Example

```bash
npm run docusaurus docs:version 1.0
```

The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.
This command:

- Copies the full `docs/` directory into a new `version-1.0` directory in the `versioned_docs` directory.
- Creates a new `versioned_sidebars/version-1.0-sidebars.json` file.
- Appends the new version number to the `versions.json` file.

<!--/tabs-->

Your docs now have two versions:

- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
- `current` at `http://localhost:3000/docs/next/` for the upcoming, unreleased docs.
- `1.0` at `http://localhost:3000/` for the version 1.0 docs
- `current` at `http://localhost:3000/next/` for the upcoming, unreleased docs.

### 2. Update the `docusaurus.config.js` file to re-label these paths

In `docusaurus.config.js`, under `presets` > `classic` > `docs`:

- Update the `lastVersion` to the new version number.
- Under `versions`, update the current version to the new version.

For example, when releasing version `1.0`, update the following section in the `docusaurus.config.js`
file by updating the version number:

```js
presets: [
[
"classic",
{
docs: {
sidebarPath: require.resolve("./sidebars.js"),
// Set a base path separate from default /docs
editUrl: "https://github.com/ConsenSys/doc.teku/tree/master/",
routeBasePath: "/",
path: "./docs",
includeCurrentVersion: true,
// highlight-next-line
lastVersion: "1.0",
versions: {
//defaults to the ./docs folder
// using 'development' instead of 'next' as path
current: {
label: "development",
path: "development",
},
//the last stable release in the versioned_docs/version-1.0
// highlight-start
"1.0": {
label: "1.0",
},
// highlight-end
},
...
],

```

### 3. Update the `versions.json` file

:::info
Please remember to remove any old versions that you are not required in this file
:::

```json
[
"1.0",
"0.x"
]
```

### 4. Delete the previous doc versions (if needed)

If you have deleted a version in step 3, also delete the artifacts for that version. For example, if deleting version `0.2` that would mean deleting the following:

1. In the `versioned_docs` directory, delete the `version-0.2` folder
2. In the `versioned_sidebars` directory, delete the `version-0.2-sidebars.json` file.

Create your pull request. You can perform a final check using the preview link generated for your PR.

## Add a version dropdown
### 5. Add a version dropdown (Do this once only when versioning is introduced)

To navigate seamlessly across versions, add a version dropdown by modifying `docusaurus.config.js`
as follows:
Expand Down Expand Up @@ -58,4 +191,4 @@ The docs version dropdown appears in your navbar:
You can edit versioned docs in their respective folder:

- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`.
- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`.
- `docs/hello.md` updates `http://localhost:3000/docs/development/hello`.
64 changes: 45 additions & 19 deletions docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,24 @@ const config = {
// Set a base path separate from default /docs
editUrl: "https://github.com/ConsenSys/docs-template/tree/main/",
routeBasePath: "/",
path: "docs",
path: "./docs",
includeCurrentVersion: true,
// lastVersion: "23.x",
// versions: {
// //defaults to the ./docs folder
// // using 'development' instead of 'next' as path
// current: {
// label: "development",
// path: "development",
// },
// //the last stable release in the versioned_docs/version-stable
// "23.x": {
// label: "stable (23.x)",
// },
// "22.x": {
// label: "22.x",
// },
// },
// @ts-ignore
// eslint-disable-next-line global-require
remarkPlugins: [require("remark-docusaurus-tabs")],
Expand All @@ -108,7 +125,6 @@ const config = {
],
showLastUpdateAuthor: true,
showLastUpdateTime: true,
includeCurrentVersion: true,
},
theme: {
customCss: require.resolve("./src/css/custom.css"),
Expand Down Expand Up @@ -275,21 +291,6 @@ const config = {
language: "nodejs",
logoClass: "nodejs",
},
// {
// highlight: "ruby",
// language: "ruby",
// logoClass: "ruby",
// },
// {
// highlight: "csharp",
// language: "csharp",
// logoClass: "csharp",
// },
// {
// highlight: "php",
// language: "php",
// logoClass: "php",
// },
],
}),
plugins: [
Expand All @@ -306,8 +307,33 @@ const config = {
containerId: "GTM-",
},
],
], // remove if not using docusaurus-plugin-openapi-docs
themes: [], // remove if not using docusaurus-plugin-openapi-docs
// This is how redirects are done
// [
// "@docusaurus/plugin-client-redirects",
// {
// redirects: [
// {
// from: "/HowTo/Get-Started/Installation-Options/Install-Binaries",
// to: "/get-started/install/install-binaries",
// },
// ],
// // its quite odd here in that its back to front - replace(to, from)
// createRedirects(existingPath) {
// if (existingPath.includes("/development")) {
// return [
// existingPath.replace("/development", "/en/latest"),
// existingPath.replace("/development", "/latest"),
// ];
// }
// if (existingPath.includes("/")) {
// return [existingPath.replace("/", "/stable")];
// }
// return undefined; // Return a falsy value: no redirect created
// },
// },
// ],
],
themes: [],
};

module.exports = config;
Loading