Skip to content

Commit 536127a

Browse files
ilg-ulilg-ul
committed
website re-generate commons
1 parent 030b91d commit 536127a

Some content is hidden

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

54 files changed

+784
-112
lines changed

‎README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11

22
[![license](https://img.shields.io/github/license/xpack/xpack.github.io)](https://github.com/xpack/xpack.github.io/blob/website/LICENSE)
33

4-
# The xPack Project web site source
4+
# The xPack Project website source
55

6-
The Docusaurus source code for the xPack Project web site.
6+
The Docusaurus source code for the xPack Project website.
77

88
## Project source
99

@@ -13,6 +13,6 @@ The source code is available on
1313
## License
1414

1515
Unless otherwise stated, the original content is released under the terms of the
16-
[MIT License](https://opensource.org/licenses/mit/),
16+
[MIT License](https://opensource.org/licenses/mit),
1717
with all rights reserved to
1818
[Liviu Ionescu](https://github.com/ilg-ul).

‎website/README.md

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,3 @@ The folder was created with:
88
```sh
99
npx create-docusaurus website classic --typescript
1010
```
11-
12-
## docusaurus-plugin-typedoc
13-
14-
This plugin uses [TypeDoc](https://typedoc.org) to generate
15-
the reference as markdown pages in `docs/api`.
16-
17-
- https://typedoc-plugin-markdown.org/plugins/docusaurus
18-
19-
```sh
20-
cd website
21-
npm install typedoc typedoc-plugin-markdown docusaurus-plugin-typedoc --save-dev
22-
```
23-
24-
[!NOTE]
25-
There is a new spec ([TSDoc](https://tsdoc.org)), pushed by
26-
Microsoft, slightly different, for example there are no
27-
categories or groups.
28-
29-
[!NOTE]
30-
There is also another plugin, `docusaurus-plugin-typedoc-api`, but
31-
it is no longer maintained.

‎website/docs/_common/_branches-details.mdx

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
<details>
7+
<summary>Branches</summary>
8+
9+
The project uses multiple branches:
10+
11+
- `master`, not actively used
12+
- `webpreview`, with the current development version
13+
- `website`, with the current content of the website; pushes to this branch automatically trigger publishes the main website
14+
- `webpreview`, with the current content of the preview website; pushes to this branch automatically trigger publishes the preview website
15+
16+
All development is done in the `webpreview` branch, and contributions via
17+
Pull Requests should be directed to this branch.
18+
19+
When new releases are published, the `webpreview` branch is merged
20+
into `website`.
21+
22+
</details>

‎website/docs/_common/_build-website-locally.mdx

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
### Build the static website locally
7+
8+
Validate the website content in a local build via the npm **build** script:
9+
10+
```sh
11+
npm run build -C website
12+
```
13+
14+
Fix any broken links, if any.

‎website/docs/_common/_code-formatting.mdx

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
## Code formatting
7+
8+
As formatting style, the library uses a
9+
[.clang-format](https://clang.llvm.org/docs/ClangFormat.html)
10+
configuration file based on the GNU style.
11+
12+
Code formatting is done using `clang-format --style=file`, either manually
13+
from a script, or automatically from Visual Studio Code, or the Eclipse
14+
CppStyle plug-in.
15+
16+
:::info
17+
18+
Visual Studio Code can directly utilise the `.clang-format` file in the
19+
**Format Document** command.
20+
21+
:::
22+
23+
:::tip
24+
25+
Always reformat the source files that were changed before committing
26+
them to the repository.
27+
28+
:::

‎website/docs/_common/_continuous-integration.mdx

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
The library undergoes continuous integration (CI) testing with every
7+
push using [GitHub Actions](https://github.com/xpack/xpack.github.io/actions).
8+
This ensures compatibility and stability across Ubuntu, macOS, and Windows
9+
operating systems.
10+
11+
The tests are conducted on both 32-bit and 64-bit bare-metal platforms,
12+
including Arm Cortex-M0, Cortex-M3, Cortex-M4F, Cortex-M7F, Cortex-A15,
13+
Cortex-A72, RISC-V RV32IMAC, and RV64IMAFDC. Additionally, native
14+
testing is performed using GCC and LLVM/clang compilers, ensuring
15+
thorough validation across various environments.

‎website/docs/_common/_generate-top-commons.mdx

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
### Generate the top commons
7+
8+
Run the top **generate-top-commons** npm script to update the
9+
`build-assets/package.json` and the GitHub workflow files.
10+
11+
```sh
12+
(cd ~/Work/xpack/xpack.github.io.git; npm run generate-top-commons)
13+
```
14+
15+
### Commit the top changes
16+
17+
- stage GitHub workflows and `package.json` files (top and from `build-assets`)
18+
- **commit** with the message _**re-generate top commons to bump deps**_

‎website/docs/_common/_generate-website-commons.mdx

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
### Update the website commons
7+
8+
Run the **generate-website-commons** npm script from `website/package.json`
9+
in the project folder.
10+
11+
```sh
12+
npm run generate-website-commons -C website
13+
```

‎website/docs/_common/_get-helper-sources-details.mdx

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
import CodeBlock from '@theme/CodeBlock';
5+
6+
{/* ------------------------------------------------------------------------ */}
7+
8+
<details>
9+
<summary>Get the writable helper sources (optional, for development purposes)</summary>
10+
11+
The project has a dependency to a common helper, that is normally installed
12+
as a read-only dependency; for development purposes, to be able to make
13+
changes to the scripts located inside the helper, clone the
14+
<code>{props.helperBranchName}</code> branch and link it to the
15+
user's global xPacks store:
16+
17+
<CodeBlock language="sh"> {
18+
`rm -rf ~/Work/${props.helperOrganizationName}/${props.helperProjectName}.git && \\
19+
mkdir -p ~/Work/${props.helperOrganizationName} && \\
20+
git clone \\
21+
\ --branch ${props.helperBranchName} \\
22+
\ https://github.com/${props.helperOrganizationName}/${props.helperProjectName}.git \\
23+
\ ~/Work/${props.helperOrganizationName}/${props.helperProjectName}.git \
24+
`} </CodeBlock>
25+
26+
Or, if the repo was already cloned:
27+
28+
<CodeBlock language="sh"> {
29+
`git -C ~/Work/${props.helperOrganizationName}/${props.helperProjectName}.git pull
30+
`} </CodeBlock>
31+
32+
If a writable instance of this library is needed in another project,
33+
add a link from the user's global xPacks store to it:
34+
35+
<CodeBlock language="sh"> {
36+
`xpm link -C ~/Work/${props.helperOrganizationName}/${props.helperProjectName}.git
37+
`} </CodeBlock>
38+
39+
</details>

‎website/docs/_common/_get-project-sources.mdx

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
import BranchesDetails from './_branches-details.mdx'
5+
6+
{/* ------------------------------------------------------------------------ */}
7+
8+
## Get project sources
9+
10+
The project is hosted on GitHub:
11+
12+
- https://github.com/xpack/xpack.github.io.git
13+
14+
<BranchesDetails />
15+
16+
To clone the stable branch (`website`), run the following commands in a
17+
terminal (on Windows use the _Git Bash_ console):
18+
19+
```sh
20+
rm -rf ~/Work/xpack/xpack.github.io.git && \
21+
mkdir -p ~/Work/xpack && \
22+
git clone \
23+
--branch website \
24+
https://github.com/xpack/xpack.github.io.git \
25+
~/Work/xpack/xpack.github.io.git
26+
```
27+
28+
<details>
29+
<summary>For development purposes, clone the `webpreview` branch.</summary>
30+
31+
```sh
32+
rm -rf ~/Work/xpack/xpack.github.io.git && \
33+
mkdir -p ~/Work/xpack && \
34+
git clone \
35+
--branch webpreview \
36+
https://github.com/xpack/xpack.github.io.git \
37+
~/Work/xpack/xpack.github.io.git
38+
```
39+
40+
</details>
41+
42+
Or, if the repo was already cloned:
43+
44+
```sh
45+
git -C ~/Work/xpack/xpack.github.io.git pull
46+
```
47+
48+
:::tip
49+
50+
To contribute Pull Requests, fork the project and be sure the **Copy the master branch only** is **disabled**.
51+
52+
Use the `xpack-development` branch and be sure you contribute the
53+
Pull Requests back to the `xpack-development` branch.
54+
55+
:::
56+
57+
## Add links for development
58+
59+
During development, it is convenient to have a writable instance of the
60+
module to make changes in parallel with the parent project.
61+
62+
To facilitate the use of a writable instance of this library in other
63+
projects, add a link from the user's global xPacks store to this local
64+
development folder:
65+
66+
```sh
67+
npm link -C ~/Work/xpack/xpack.github.io.git
68+
```
69+
70+
And in the projects referring it:
71+
72+
```sh
73+
npm link xpack.github.io
74+
```
75+

‎website/docs/_common/_manual-tests.mdx

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
import CommonXpmCleanUps from '@site/docs/_common/_xpm-clean-ups.mdx';
5+
6+
{/* ------------------------------------------------------------------------ */}
7+
8+
### Manual tests
9+
10+
There are predefined xpm actions available to manually run various
11+
tests on the local development machine.
12+
13+
It is recommended to begin by performing some clean-ups (not necessary
14+
after the initial `git clone`):
15+
16+
```sh
17+
npm install -C ~/Work/xpack/xpack.github.io.git/tests
18+
xpm run deep-clean -C ~/Work/xpack/xpack.github.io.git/tests
19+
```
20+
21+
:::tip
22+
23+
During the initial run, the installation step may take a considerable
24+
amount of time, as it needs to download the toolchain archives, which
25+
can be relatively large, up to several hundred megabytes.
26+
27+
:::
28+
29+
To run the tests with the system compiler (usually not available on Windows):
30+
31+
```sh
32+
xpm run install -C ~/Work/xpack/xpack.github.io.git/tests
33+
xpm run test -C ~/Work/xpack/xpack.github.io.git/tests
34+
```
35+
36+
To run a selection of tests with the latest versions of toolchains:
37+
38+
```sh
39+
xpm run install-selected -C ~/Work/xpack/xpack.github.io.git/tests
40+
xpm run test-selected -C ~/Work/xpack/xpack.github.io.git/tests
41+
```
42+
43+
To run all tests with the latest versions of toolchains:
44+
45+
```sh
46+
xpm run install-latest -C ~/Work/xpack/xpack.github.io.git/tests
47+
xpm run test-latest -C ~/Work/xpack/xpack.github.io.git/tests
48+
```
49+
50+
To run all tests with all toolchain versions:
51+
52+
```sh
53+
xpm run install-all -C ~/Work/xpack/xpack.github.io.git/tests
54+
xpm run test-all -C ~/Work/xpack/xpack.github.io.git/tests
55+
```
56+
57+
### Clean-ups
58+
59+
Running all tests may require several gigabytes of space.
60+
61+
To clean up the tests folder, use:
62+
63+
```sh
64+
npm install -C ~/Work/xpack/xpack.github.io.git/tests
65+
xpm run deep-clean -C ~/Work/xpack/xpack.github.io.git/tests
66+
```
67+
68+
A considerable amount of space may also be used by the toolchains.
69+
When no longer needed, they can be removed with `xpm uninstall`.
70+
71+
<details>
72+
<summary>xpm clean-ups</summary>
73+
74+
<CommonXpmCleanUps />
75+
76+
</details>

‎website/docs/_common/_prepare-website.mdx

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
### Prepare the website
7+
8+
The documentation site is built with [Docusaurus](https://docusaurus.io) and
9+
published in the project
10+
[GitHub Pages](https://xpack.github.io/).
11+
12+
- switch to the `webpreview` branch
13+
- run the **website-generate-commons** npm script in the `website/package.json`
14+
```sh
15+
npm run website-generate-commons -C website
16+
```
17+
- **commit** all changes

‎website/docs/developer/_common/_prerequisites.mdx renamed to ‎website/docs/_common/_prerequisites.mdx

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@ import CodeBlock from '@theme/CodeBlock';
77

88
## Prerequisites
99

10-
**xpack.github.io** is a portable Node.js module;
10+
**xpack.github.io** is
11+
a portable Node.js module;
1112
development can be
12-
performed on macOS, GNU/Linux and even Windows (although some npm scripts
13+
carried out on macOS, GNU/Linux and even Windows (although some npm scripts
1314
must be executed in a Git Bash terminal).
1415

1516
The prerequisites are:
@@ -18,6 +19,7 @@ The prerequisites are:
1819
- node >= {props.nodeVersion || 'N.N.N'}
1920
- npm
2021

22+
2123
To ensure compatibility with older node, preferably revert to an older one:
2224

2325
<CodeBlock language="console"> {

0 commit comments

Comments
 (0)