Skip to content

Commit 795d934

Browse files
renardeinsideJCZuurmondgueniai
authored
✨ introduce docs (#3458)
New docs incoming! Tech: - Docusaurus - TailwindCSS For details on authoring the docs, please check: docs/ucx/docs/dev/docs_authoring.mdx For docs deployment pipeline please check: .github/workflows/docs-release.yml This PR doesn't change most of the content, rather just forms it into 4 categories: - Installation - Process - Reference (includes commands, codes, etc.) Feature wise: - 100% Docusaurus and MDX - Auto-link checking, checks both links and anchors! - Cool landing page - Clickable images To setup the env and run/edit docs locally, please use instructions in `docs/ucx/docs/dev/docs_authoring.mdx`. Target URL for docs after deployment is https://databrickslabs.github.io/ucx/ Some screenshots: ![image](https://github.com/user-attachments/assets/b9b3d208-87c5-4984-8e69-a8e09b50b8b6) ![image](https://github.com/user-attachments/assets/06fb48f3-c8fc-422e-90df-841a4a4f4b4b) --------- Co-authored-by: Cor <[email protected]> Co-authored-by: Guenia Izquierdo Delgado <[email protected]>
1 parent 796e80d commit 795d934

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

+14055
-2945
lines changed

‎.github/workflows/docs-release.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Docs Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
workflow_dispatch: # Enables manual triggering of the workflow
8+
9+
jobs:
10+
build:
11+
name: Build Docusaurus
12+
runs-on:
13+
group: databrickslabs-protected-runner-group
14+
labels: linux-ubuntu-latest
15+
defaults:
16+
run:
17+
working-directory: docs/ucx
18+
steps:
19+
- uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
- uses: actions/setup-node@v4
23+
with:
24+
node-version: 20
25+
cache: yarn
26+
cache-dependency-path: docs/ucx/yarn.lock # need to put the lockfile path explicitly
27+
28+
- name: Install dependencies
29+
run: yarn install --frozen-lockfile
30+
- name: Build website
31+
run: yarn build
32+
33+
- name: Upload Build Artifact
34+
uses: actions/upload-pages-artifact@v3
35+
with:
36+
path: docs/ucx/build
37+
38+
deploy:
39+
name: Deploy to GitHub Pages
40+
needs: build
41+
runs-on:
42+
group: databrickslabs-protected-runner-group
43+
labels: linux-ubuntu-latest
44+
45+
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
46+
permissions:
47+
pages: write # to deploy to Pages
48+
id-token: write # to verify the deployment originates from an appropriate source
49+
50+
# Deploy to the github-pages environment
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
55+
56+
steps:
57+
- name: Deploy to GitHub Pages
58+
id: deployment
59+
uses: actions/deploy-pages@v4

‎Makefile‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,15 @@ solacc:
3232
hatch run python tests/integration/source_code/solacc.py
3333

3434
.PHONY: all clean dev lint fmt test integration coverage known solacc
35+
36+
docs-install:
37+
yarn --cwd docs/ucx install
38+
39+
docs-serve-dev:
40+
yarn --cwd docs/ucx start
41+
42+
docs-build:
43+
yarn --cwd docs/ucx build
44+
45+
docs-serve: docs-build
46+
yarn --cwd docs/ucx serve

‎README.md‎

Lines changed: 19 additions & 2346 deletions
Large diffs are not rendered by default.

‎docs/ucx/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎CONTRIBUTING.md‎ renamed to ‎docs/ucx/docs/dev/contributing.mdx‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Contributing
1+
2+
import Admonition from '@theme/Admonition';
3+
4+
# Developer Guide
25

36
## First Principles
47

@@ -27,7 +30,7 @@ or specialized functionality unavailable in standard libraries.
2730

2831
## Adding entries to `known.json` file
2932

30-
When adding a new entry to the [`known.json` file](src/databricks/labs/ucx/source_code/known.json), ensure that the entry is unique and follows the correct format. The `known.json` file
33+
When adding a new entry to the [`known.json` file](https://github.com/databrickslabs/ucx/blob/main/src/databricks/labs/ucx/source_code/known.json), ensure that the entry is unique and follows the correct format. The `known.json` file
3134
stores information about known (in)compatibilities with Unity Catalog. The file speeds up static code analysis and prevents false positives.
3235

3336
1. load into virtual environment
@@ -214,7 +217,7 @@ with the [Python plugin (Community Edition)](https://plugins.jetbrains.com/plugi
214217
IntelliJ CE, then it would work in PyCharm. Debugging capabilities are essential for troubleshooting and diagnosing issues during
215218
development. Please make sure that your test setup allows for easy debugging by following best practices.
216219

217-
![debugging tests](docs/debugging-tests.gif)
220+
![debugging tests](/img/debugging-tests.gif)
218221

219222
Adhering to these guidelines ensures that our integration tests are robust, efficient, and easily maintainable. This,
220223
in turn, contributes to the overall reliability and quality of our software.
@@ -263,7 +266,7 @@ HATCH_PYTHON="$(which python3.10)" make clean dev test
263266
```
264267

265268
Configure your IDE to use `.venv/bin/python` from the virtual environment when developing the project:
266-
![IDE Setup](docs/hatch-intellij.gif)
269+
![IDE Setup](/img/hatch-intellij.gif)
267270

268271

269272
Verify installation with
@@ -403,6 +406,11 @@ $ python3.10 -m pip install hatch
403406
$ make dev
404407
$ make test
405408
```
406-
Note: Before performing a clean installation, deactivate the virtual environment and follow the commands given above.
407409

408-
Note: The initial `hatch env show` is just to list the environments managed by Hatch and is not needed.
410+
<Admonition type="info" title="Deactivating the Virtual Environment">
411+
Before performing a clean installation, deactivate the virtual environment and follow the commands given above.
412+
</Admonition>
413+
414+
<Admonition type="note" title="Env command">
415+
The initial `hatch env show` is just to list the environments managed by Hatch and is not needed.
416+
</Admonition>

‎docs/ucx/docs/dev/docs_authoring.mdx‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
import Admonition from '@theme/Admonition';
2+
3+
# Authoring Documentation
4+
5+
This document provides guidelines for writing documentation for the UCX project.
6+
7+
8+
## Tech Stack
9+
10+
The UCX documentation is built using [Docusaurus](https://docusaurus.io/), a modern static site generator. Docusaurus is a project of Facebook Open Source and is used by many open-source projects to build their documentation websites.
11+
We also use [MDX](https://mdxjs.com/) to write markdown files that include JSX components. This allows us to write markdown files with embedded React components.
12+
For styling, we use [Tailwind CSS](https://tailwindcss.com/), a utility-first CSS framework for rapidly building custom designs.
13+
14+
## Writing Documentation
15+
16+
Most of the documentation is written in markdown files with the `.mdx` extension.
17+
The markdown files are located in the `docs` directory of the UCX project.
18+
19+
## Prerequisites
20+
21+
Before you start writing documentation, make sure you have the following tools installed on your machine:
22+
- [Node.js](https://nodejs.org/en/)
23+
- [Yarn](https://yarnpkg.com/)
24+
25+
On macOS, you can install Node.js and Yarn using [Homebrew](https://brew.sh/):
26+
27+
```bash
28+
brew install node
29+
npm install --global yarn
30+
```
31+
32+
33+
## Setup
34+
35+
To set up the documentation locally, follow these steps:
36+
37+
1. Clone the UCX repository
38+
2. Run:
39+
40+
```bash
41+
make docs-install
42+
```
43+
44+
## Running the Documentation Locally
45+
46+
To run the documentation locally, use the following command:
47+
48+
```bash
49+
make docs-serve-dev
50+
```
51+
## Checking search functionality
52+
53+
<Admonition type="tip" title="Tip" emoji="💡">
54+
We're using local search, and it won't be available in the development server.
55+
</Admonition>
56+
57+
To check the search functionality, run the following command:
58+
59+
```bash
60+
make docs-serve
61+
```
62+
63+
## Adding images
64+
65+
To add images to your documentation, place the image files in the `static/img` directory.
66+
67+
To include an image in your markdown file, use the following syntax:
68+
69+
```markdown
70+
![Alt text](/img/image-name.png)
71+
```
72+
73+
<Admonition type="tip" title="Tip" emoji="💡">
74+
Images support zooming features out of the box.
75+
</Admonition>
76+
77+
## Linking pages
78+
79+
It is **strongly** recommended to make all links absolute.
80+
By doing so we ensure that it's easy to move files without losing links inside them.
81+
82+
To add an absolute link, use this syntax:
83+
84+
```md
85+
[link text](/docs/folder/file_name)
86+
```
87+
88+
Always start with `/docs`. The file extension `.md` or `.mdx` can be omitted.
89+
90+
To add an anchor to a specific heading, use this syntax:
91+
92+
```md
93+
[link with anchor](/docs/folder/file_name#anchor)
94+
```
95+
96+
After writing docs, run this command:
97+
98+
```
99+
make docs-build
100+
```
101+
102+
It will throw an error on any unresolved link or anchor.
103+
104+
105+
## Content alignment and structure of folders
106+
107+
When writing documentation, make sure to align the content with the existing documentation.
108+
109+
The rule of thumb is:
110+
111+
<div className="text-red-700 p-4 dark:text-red-400 flex justify-center items-center">
112+
<div className='max-w-screen-sm text-center text-balance'>
113+
<div className="text-2xl font-bold font-mono text-balance">
114+
Do not put any technical details in the main documentation.
115+
</div>
116+
<div className="text-lg font-mono">
117+
All technical details should be kept in <code>/docs/dev/</code> section.
118+
</div>
119+
</div>
120+
</div>
121+
122+
No need for:
123+
- Source code links
124+
- Deep technical details
125+
- Implementation details
126+
127+
Or any other details that are not necessary for the **end-user**.
128+
129+
## Deployment
130+
131+
The UCX documentation is hosted on GitHub Pages, and the deployment process is automated using GitHub Actions.
132+
133+
To configure the deployment process, you need to have admin permissions on the repo:
134+
1. go to the repository settings -> Pages
135+
2. In the "Build and deployment" section select the `Github Actions` source.
136+
137+
The deployment process is triggered automatically when a release is created.
138+
Also, the deployment process can be triggered manually from the `Actions` tab in the GitHub repository by privileged users.

‎docs/ucx/docs/dev/index.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
# Contributing to UCX
6+
7+
This section is for contributors to the UCX toolkit. It contains information on how to contribute to the toolkit, including how to submit issues, pull requests, and how to contribute to the documentation.

0 commit comments

Comments
 (0)