Skip to content

Commit fde892c

Browse files
vascoalramosaquemy
vascoalramos
authored and
aquemy
committed
docs: setup new docs with mkdocs (#1418)
1 parent 1bf0bb8 commit fde892c

222 files changed

Lines changed: 3112 additions & 5197 deletions

File tree

Some content is hidden

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

‎.github/workflows/docs.yaml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
name: Publish Documentation
2+
3+
4+
5+
on:
6+
push:
7+
paths:
8+
- .github/workflows/docs.yaml
9+
- docs/**
10+
- examples/**
11+
- mkdocs.yml
12+
- requirements-docs.txt
13+
branches:
14+
- main
15+
release:
16+
types:
17+
- released
18+
19+
20+
21+
jobs:
22+
prepare:
23+
name: Get Current version
24+
runs-on: ubuntu-22.04
25+
26+
outputs:
27+
version: ${{ steps.version.outputs.value }}
28+
29+
steps:
30+
- uses: actions/checkout@v3
31+
with:
32+
token: ${{ secrets.ACCESS_TOKEN }}
33+
34+
- name: Find Latest Tag
35+
id: latest_tag
36+
uses: oprypin/find-latest-tag@v1.1.1
37+
with:
38+
repository: ${{ github.repository }}
39+
regex: '^v\d+\.\d+\.\d+$'
40+
41+
- name: Extract major and minor version
42+
id: version
43+
run: |
44+
echo "value=`echo ${{ steps.latest_tag.outputs.tag }} | sed -r 's|v([0-9]+.[0-9]+).*|\1|g'`" >> $GITHUB_OUTPUT
45+
46+
47+
publish-docs:
48+
name: Publish Docs
49+
runs-on: ubuntu-22.04
50+
51+
needs:
52+
- prepare
53+
54+
steps:
55+
- uses: actions/checkout@v3
56+
with:
57+
fetch-depth: 0
58+
token: ${{ secrets.ACCESS_TOKEN }}
59+
60+
- name: Configurating Git
61+
run: |
62+
git config user.email "azory@ydata.ai"
63+
git config user.name "Azory YData Bot"
64+
git config core.autocrlf false
65+
66+
- name: Setup Python
67+
uses: actions/setup-python@v4
68+
with:
69+
python-version: "3.10"
70+
71+
- name: Cache pip dependencies
72+
id: cache
73+
uses: actions/cache@v3
74+
with:
75+
path: ~/.cache/pip
76+
key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
77+
78+
- name: Install doc dependencies
79+
run: |
80+
python -m pip install --upgrade pip
81+
make install-docs
82+
83+
- name: Publish
84+
run: make publish-docs version=${{ needs.prepare.outputs.version }}

‎.github/workflows/merge-master.yml‎

Lines changed: 0 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -41,71 +41,6 @@ jobs:
4141
run: echo "value=${{ steps.semantic.outputs.new_release_version }}.rc${{ steps.build_number.outputs.value }}" >> $GITHUB_OUTPUT
4242

4343

44-
docs-changelog:
45-
if: needs.prepare.outputs.new_release == 'true'
46-
name: Update changelog on docs
47-
runs-on: ubuntu-22.04
48-
49-
needs: prepare
50-
51-
steps:
52-
- uses: actions/checkout@v4
53-
with:
54-
fetch-depth: 0
55-
token: ${{ secrets.ACCESS_TOKEN }}
56-
57-
- name: Calculate changelog path
58-
id: path
59-
run: echo "value=$(echo "${{ needs.prepare.outputs.release }}" | sed "s/\./_/g").md" >> $GITHUB_OUTPUT
60-
61-
- name: Configure Git
62-
run: |
63-
git config user.email "azory@ydata.ai"
64-
git config user.name "Azory YData Bot"
65-
git config core.autocrlf false
66-
67-
- name: Write changelog to file
68-
uses: DamianReeves/write-file-action@master
69-
with:
70-
path: docsrc/source/pages/reference/changelog/${{ steps.path.outputs.value }}
71-
contents: ${{ needs.prepare.outputs.release_notes }}
72-
write-mode: overwrite
73-
74-
- name: Add changelog to docs
75-
run: |
76-
cd docsrc/source/pages/reference
77-
sed -i -e 's/## \[.*/### Changelog ${{ needs.prepare.outputs.release }}/g' \
78-
-e 's/### Bug Fixes/#### 🐛 Bug fixes/g' \
79-
-e 's/### Features/#### 🎉 Features/g' \
80-
-e 's/### BREAKING CHANGES/#### 🚨 Breaking changes/g' \
81-
-e 's/### Documentation/#### 📖 Documentation/g' \
82-
changelog/${{ steps.path.outputs.value }}
83-
84-
grep -q ".. include:: changelog/${{ steps.path.outputs.value }}" changelog.rst || sed -i "4 a\\
85-
.. include:: changelog\/${{ steps.path.outputs.value }}\\
86-
:parser: myst_parser.sphinx_\\
87-
88-
" changelog.rst
89-
90-
- name: Commit changelog
91-
id: commit
92-
run: |
93-
if [[ `git status --porcelain` ]]; then
94-
echo "CHANGES=true" >> $GITHUB_OUTPUT
95-
git add docsrc/source/pages/reference/changelog/${{ steps.path.outputs.value }}
96-
git commit -m "[skip ci] Update changelogs" -a
97-
else
98-
echo "CHANGES=false" >> $GITHUB_OUTPUT
99-
fi
100-
101-
- name: Push changes
102-
uses: ad-m/github-push-action@v0.6.0
103-
if: ${{ steps.commit.outputs.CHANGES == 'true' }}
104-
with:
105-
branch: ${{ github.ref }}
106-
github_token: ${{ secrets.ACCESS_TOKEN }}
107-
108-
10944
prerelease-tag:
11045
if: needs.prepare.outputs.new_release == 'true'
11146

@@ -132,7 +67,6 @@ jobs:
13267

13368
needs:
13469
- prepare
135-
- docs-changelog
13670

13771
steps:
13872
- name: Delete Previous drafts

‎.github/workflows/pull-request.yml‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
name: Pull Request
22

3-
43
on:
54
push:
65
branches:
@@ -18,7 +17,7 @@ jobs:
1817
fetch-depth: 0
1918

2019
- uses: wagoid/commitlint-github-action@v5
21-
20+
2221
lint:
2322
if: github.actor != 'renovate[bot]'
2423
name: Lint source code
@@ -40,7 +39,7 @@ jobs:
4039
- name: Set up Python 3.8
4140
uses: actions/setup-python@v4
4241
with:
43-
python-version: 3.8
42+
python-version: "3.10"
4443

4544
- uses: actions/cache@v3
4645
name: Cache pip dependencies
@@ -81,3 +80,36 @@ jobs:
8180
with:
8281
branch: ${{ github.head_ref }}
8382
github_token: ${{ secrets.ACCESS_TOKEN }}
83+
84+
validate-docs:
85+
name: Validate Docs
86+
runs-on: ubuntu-22.04
87+
88+
steps:
89+
- uses: actions/checkout@v3
90+
91+
- name: Setup Python
92+
uses: actions/setup-python@v4
93+
with:
94+
python-version: "3.10"
95+
96+
- name: Cache pip dependencies
97+
id: cache
98+
uses: actions/cache@v3
99+
with:
100+
path: ~/.cache/pip
101+
key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
102+
103+
- name: Install dependencies
104+
run: |
105+
python -m pip install --upgrade pip
106+
python -m pip install -r requirements.txt
107+
python -m pip install -r requirements-dev.txt
108+
python -m pip install -r requirements-test.txt
109+
python -m pip install -r requirements-docs.txt
110+
111+
- name: Install the package
112+
run: make install
113+
114+
- name: Build docs
115+
run: mkdocs build

‎.github/workflows/release.yml‎

Lines changed: 3 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ name: Release
44
on:
55
release:
66
types:
7-
- released
7+
- released
88

99

1010
jobs:
@@ -19,10 +19,10 @@ jobs:
1919
id: version
2020
run: echo "value=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
2121

22-
- name: Setup Python 3.8
22+
- name: Setup Python 3.10
2323
uses: actions/setup-python@v4
2424
with:
25-
python-version: "3.8"
25+
python-version: "3.10"
2626

2727
- uses: actions/cache@v3
2828
name: Cache pip dependencies
@@ -89,67 +89,3 @@ jobs:
8989
with:
9090
user: __token__
9191
password: ${{ secrets.PYPI_API_TOKEN }}
92-
93-
docs_and_examples:
94-
name: Documentation and Examples
95-
runs-on: ubuntu-22.04
96-
97-
steps:
98-
- uses: actions/checkout@v4
99-
100-
- name: Configurating Git
101-
run: |
102-
git config user.email "azory@ydata.ai"
103-
git config user.name "Azory YData Bot"
104-
git config core.autocrlf false
105-
106-
- name: Set up Python 3.8
107-
uses: actions/setup-python@v4
108-
with:
109-
python-version: 3.8
110-
111-
- name: Install pip dependencies
112-
run: |
113-
pip install --upgrade pip
114-
pip install -r requirements.txt
115-
pip install -r requirements-dev.txt
116-
pip install -r requirements-test.txt
117-
118-
- name: Install the package
119-
run: |
120-
make install
121-
122-
- name: Update examples
123-
run: make examples
124-
125-
- name: Build the documentation
126-
run: make docs
127-
128-
- name: Move the changes to the gh-pages branch (release branch)
129-
run: |
130-
mv docs master
131-
mkdir docs
132-
mv master docs/master
133-
mv examples/ master
134-
mkdir examples
135-
mv master examples/master
136-
git add -f docs/master
137-
git add -f examples/master
138-
git stash push -- docs/master examples/master
139-
git fetch origin gh-pages
140-
git checkout -f gh-pages
141-
touch .nojekyll
142-
git add .nojekyll
143-
rm -rf docs/master
144-
rm -rf examples/master
145-
git add docs/
146-
git add examples/
147-
git stash apply
148-
git commit -m "[skip ci] Updating documentation and examples" -a || true
149-
150-
- name: Push changes
151-
uses: ad-m/github-push-action@master
152-
with:
153-
branch: gh-pages
154-
directory: .
155-
github_token: ${{ secrets.ACCESS_TOKEN }}

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ __pycache__/
88

99
# Distribution / packaging
1010
.Python
11+
.venv
1112
env/
1213
build/
1314
develop-eggs/
@@ -77,7 +78,7 @@ playground/
7778
# build data
7879
examples/*/*.html
7980
examples/*/*.csv
80-
docs/
81+
static/docs
8182
docsrc/_build/
8283
docsrc/source/pages/api/_autosummary/
8384

‎Makefile‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,7 @@
11
.PHONY: docs examples
22

33
docs:
4-
rm -rf docs/
5-
mkdir docs/
6-
# sphinx
7-
cd docsrc/ && make github
4+
mkdocs build
85

96
test:
107
pytest tests/unit/
@@ -34,13 +31,21 @@ package:
3431
install:
3532
pip install -e .[notebook]
3633

34+
install-docs: install ### Installs regular and docs dependencies
35+
pip install -r requirements-docs.txt
36+
3737
install-spark-ci:
3838
sudo apt-get update
3939
sudo apt-get -y install openjdk-8-jdk
4040
curl https://archive.apache.org/dist/spark/spark-${SPARK_VERSION}/spark-${SPARK_VERSION}-bin-hadoop${HADOOP_VERSION}.tgz \
4141
--output ${SPARK_DIRECTORY}/spark.tgz
4242
cd ${SPARK_DIRECTORY} && tar -xvzf spark.tgz && mv spark-${SPARK_VERSION}-bin-hadoop${HADOOP_VERSION} spark
4343

44+
publish-docs: examples ### Publishes the documentation
45+
mkdir docs/examples
46+
rsync -R examples/*/*.html docs
47+
mike deploy --push --update-aliases $(version) latest
48+
4449
lint:
4550
pre-commit run --all-files
4651

‎docs/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# YData Profiling Documentation
2+
3+
Installing the documentation dependencies (one time step):
4+
```bash
5+
make install-docs
6+
```
7+
8+
Build the doc for deployment:
9+
```
10+
mkdocs build
11+
```
12+
13+
To build and serve locally:
14+
```
15+
mkdocs serve
16+
```

docsrc/assets/cli.png renamed to docs/_static/img/cli.png

File renamed without changes.

docsrc/source/_static/figure-git-workflow.svg renamed to docs/_static/img/figure-git-workflow.svg

File renamed without changes.

docsrc/assets/iframe.gif renamed to docs/_static/img/iframe.gif

File renamed without changes.

0 commit comments

Comments
 (0)