From 7f7a550601212c9c3335d3350a5c0e5cd8fcf7db Mon Sep 17 00:00:00 2001 From: Stijn de Gooijer Date: Mon, 28 Aug 2023 10:41:08 +0200 Subject: [PATCH] Add docs workflow --- .github/workflows/docs-global.yml | 63 +++++++++++++++++++ docs/Contributing.md | 4 +- docs/README.md | 4 +- docs/docs/snippets/under_construction.md | 2 +- docs/docs/user-guide/misc/contributing.md | 4 +- docs/workflows/ci.yaml | 73 ----------------------- docs/workflows/deploy.yaml | 24 -------- 7 files changed, 70 insertions(+), 104 deletions(-) create mode 100644 .github/workflows/docs-global.yml delete mode 100644 docs/workflows/ci.yaml delete mode 100644 docs/workflows/deploy.yaml diff --git a/.github/workflows/docs-global.yml b/.github/workflows/docs-global.yml new file mode 100644 index 000000000000..4b18124fa092 --- /dev/null +++ b/.github/workflows/docs-global.yml @@ -0,0 +1,63 @@ +name: Build Polars documentation + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: write + +defaults: + run: + shell: bash + working-directory: docs + +jobs: + test-python: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - run: pip install -r requirements.txt + + - name: Install graphviz + # uses: ts-graphviz/setup-graphviz@v1 + run: sudo apt-get install -y graphviz + + - run: find docs/src/ -name "*.py" | xargs -n 1 sh -c 'python $0 || exit 255' + + black: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: '3.11' + - run: pip install black==23.3.0 + - run: black --check . + + markdown-link-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: gaurav-nelson/github-action-markdown-link-check@v1 + + deploy: + needs: [test-python, black, rome, test-node, markdown-link-check] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.11 + + - run: pip install -r requirements.txt + + - run: sudo apt-get install -y graphviz + + - run: mkdocs gh-deploy --force diff --git a/docs/Contributing.md b/docs/Contributing.md index d7ddbd1e0c39..bbade77c3d36 100644 --- a/docs/Contributing.md +++ b/docs/Contributing.md @@ -16,9 +16,9 @@ We use GitHub to host code, to track issues and feature requests, as well as acc 1. Fork the [repo](https://github.com/pola-rs/polars-book.git) in your own GitHub account. 1. Clone your own version of the repo locally, and `cd` into it. 1. Add the upstream remote with `git remote add upstream https://github.com/pola-rs/polars-book.git` -1. All branches should derive from `master`, you can `git checkout -b ` and write away. +1. All branches should derive from `main`, you can `git checkout -b ` and write away. 1. Commit/push to your own repo. -1. Open a pull request as you would usually do, making sure the "base repository" is the upstream repo (`master` branch) and the "head repository" your own (`` branch). +1. Open a pull request as you would usually do, making sure the "base repository" is the upstream repo (`main` branch) and the "head repository" your own (`` branch). To update your own repo with code pushed on the upstream repo: diff --git a/docs/README.md b/docs/README.md index cef0e177bba2..20d19a02c51c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,9 +15,9 @@ In order to serve the books run `make serve`. This will run all the python examp ## Deployment -Deployment of the book is done using Github Pages and Github Workflows. The book is automatically deployed on each push to master / main branch. There are a number of checks in the CI pipeline to avoid non-working examples: +Deployment of the book is done using Github Pages and Github Workflows. The book is automatically deployed on each push to main branch. There are a number of checks in the CI pipeline to avoid non-working examples: - Run all python examples, fail on any errors - Run all node examples, fail on any errors - Check all links in markdown -- Run black formatter \ No newline at end of file +- Run black formatter diff --git a/docs/docs/snippets/under_construction.md b/docs/docs/snippets/under_construction.md index b9eb58223380..9a5c8bb3f454 100644 --- a/docs/docs/snippets/under_construction.md +++ b/docs/docs/snippets/under_construction.md @@ -1,4 +1,4 @@ !!! warning ":construction: Under Construction :construction: " This section is still under development. Want to help out? Consider contributing and making a [pull request](https://github.com/pola-rs/polars-book) to our repository. - Please read our [Contribution Guidelines](https://github.com/pola-rs/polars-book/blob/master/CONTRIBUTING.md) on how to proceed. \ No newline at end of file + Please read our [Contribution Guidelines](https://github.com/pola-rs/polars-book/blob/main/CONTRIBUTING.md) on how to proceed. diff --git a/docs/docs/user-guide/misc/contributing.md b/docs/docs/user-guide/misc/contributing.md index 2e3774367b1e..adce0510025e 100644 --- a/docs/docs/user-guide/misc/contributing.md +++ b/docs/docs/user-guide/misc/contributing.md @@ -1,6 +1,6 @@ # Contributing -See the [`CONTRIBUTING.md`](https://github.com/pola-rs/polars/blob/master/CONTRIBUTING.md) if you would like to contribute to the `Polars` project. +See the [`CONTRIBUTING.md`](https://github.com/pola-rs/polars/blob/main/CONTRIBUTING.md) if you would like to contribute to the `Polars` project. If you're new to this we recommend starting out with contributing examples to the Python API documentation. The Python API docs are generated from the docstrings of the Python wrapper located in `polars/py-polars`. @@ -8,4 +8,4 @@ Here is an example [commit](https://github.com/pola-rs/polars/pull/3567/commits/ If you spot any gaps in this User Guide you can submit fixes to the [`pola-rs/polars-book`](https://github.com/pola-rs/polars-book) repo. -Happy hunting! \ No newline at end of file +Happy hunting! diff --git a/docs/workflows/ci.yaml b/docs/workflows/ci.yaml deleted file mode 100644 index a8ae3b8b1416..000000000000 --- a/docs/workflows/ci.yaml +++ /dev/null @@ -1,73 +0,0 @@ -name: ci -on: - pull_request: - branches: - - master - - main - push: - branches: - - master - - main -permissions: - contents: write -jobs: - - test-python: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v4 - with: - python-version: 3.x - - uses: actions/cache@v2 - with: - key: ${{ github.ref }} - path: .cache - - run: pip install -r requirements.txt - - name: Install graphviz - run: sudo apt-get install -y graphviz - - run: find docs/src/ -name "*.py" | xargs -n 1 sh -c 'python $0 || exit 255' - - black: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v4 - with: - python-version: 3.x - - uses: actions/cache@v2 - with: - key: ${{ github.ref }} - path: .cache - - run: pip install black==23.3.0 - - run: black --check . - rome: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: 18.x - - run: npm install --save-dev --save-exact rome - - run: npx rome format docs/src/node/ - - - test-node: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: 18.x - - name: Install Polars - run: npm i -s nodejs-polars - - name: Install rng - run: npm i -s chance - - name: Run code snippets - run: find docs/src/ -name "*.js" | xargs -n 1 sh -c 'node $0 || exit 255' - - markdown-link-check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@master - - uses: gaurav-nelson/github-action-markdown-link-check@v1 diff --git a/docs/workflows/deploy.yaml b/docs/workflows/deploy.yaml deleted file mode 100644 index 0a7c90d76e45..000000000000 --- a/docs/workflows/deploy.yaml +++ /dev/null @@ -1,24 +0,0 @@ -name: deploy -on: - workflow_dispatch: - push: - branches: - - master - - main -permissions: - contents: write -jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v4 - with: - python-version: 3.x - - uses: actions/cache@v2 - with: - key: ${{ github.ref }} - path: .cache - - run: pip install -r requirements.txt - - run: sudo apt-get install -y graphviz - - run: mkdocs gh-deploy --force