tinkoff-ai · Mr-Geekman · Jul 20, 2023 · Jul 20, 2023 · Jul 20, 2023 · Jul 27, 2023
diff --git a/.github/workflows/docs-on-pr.yml b/.github/workflows/docs-on-pr.yml
@@ -5,51 +5,50 @@ on:
  types: [opened, synchronize]
 
 jobs:
- build-docs:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v2
- - name: Set up Python
- uses: actions/setup-python@v2
- with:
- python-version: "3.8"
- - name: Install Poetry
- uses: snok/install-poetry@v1
- with:
- virtualenvs-create: true
- virtualenvs-in-project: true
- - name: Load cached venv
- id: cached-poetry-dependencies
- uses: actions/cache@v2
- with:
- path: .venv
- key: venv-${{ runner.os }}-docs-${{ hashFiles('**/poetry.lock') }}
- - name: Install dependencies
- if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
- run: |
- poetry install -E "all docs" -vv
- - name: Install apt docs dependencies
- run: |
- sudo apt install pandoc
- - name: Build docs
- run: |
- cd docs
- cp ../examples/*.ipynb source/tutorials
- poetry run make clean ; poetry run make html
- mv build/html/ ../site
- env:
- CI_COMMIT_SHORT_SHA: ${{ github.sha }}
- WORKFLOW_NAME: ${{ github.workflow }}
- - name: Deploy to Netlify
- uses: nwtgck/actions-netlify@v1.2
- with:
- publish-dir: './site'
- production-branch: master
- alias: deploy-preview-${{ github.event.number }}
- production-deploy: false
- deploy-message: "Deploy from GitHub Actions"
- github-token: ${{ secrets.GITHUB_TOKEN }}
- enable-commit-comment: true
- env:
- NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
- NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+ build-docs:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - name: Set up Python
+ uses: actions/setup-python@v2
+ with:
+ python-version: "3.8"
+ - name: Install Poetry
+ uses: snok/install-poetry@v1
+ with:
+ virtualenvs-create: true
+ virtualenvs-in-project: true
+ - name: Load cached venv
+ id: cached-poetry-dependencies
+ uses: actions/cache@v2
+ with:
+ path: .venv
+ key: venv-${{ runner.os }}-docs-${{ hashFiles('**/poetry.lock') }}
+ - name: Install dependencies
+ if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+ run: |
+ poetry install -E "all docs" -vv
+ - name: Install apt docs dependencies
+ run: |
+ sudo apt install pandoc
+ - name: Build docs
+ run: |
+ cd docs
+ poetry run make build-docs
+ mv build/html/ ../site
+ env:
+ CI_COMMIT_SHORT_SHA: ${{ github.sha }}
+ WORKFLOW_NAME: ${{ github.workflow }}
+ - name: Deploy to Netlify
+ uses: nwtgck/actions-netlify@v1.2
+ with:
+ publish-dir: './site'
+ production-branch: master
+ alias: deploy-preview-${{ github.event.number }}
+ production-deploy: false
+ deploy-message: "Deploy from GitHub Actions"
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ enable-commit-comment: true
+ env:
+ NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+ NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
diff --git a/.github/workflows/docs-unstable.yml b/.github/workflows/docs-unstable.yml
@@ -35,8 +35,7 @@ jobs:
  - name: Build docs
  run: |
  cd docs
- cp ../examples/*.ipynb source/tutorials
- poetry run make clean ; poetry run make html
+ poetry run make build-docs
  mv build/html/ ../site
  env:
  CI_COMMIT_SHORT_SHA: ${{ github.sha }}

diff --git a/.gitignore b/.gitignore
@@ -132,7 +132,8 @@ poetry.toml
 *.html
 *.db
 .devcontainer
-/docs/source/api/
+/docs/source/api_reference/api/
 tmp
 wandb
 !examples/wandb
+/docs/source/tutorials/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,16 +13,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Notebook `feature_selection` ([#875](https://github.com/tinkoff-ai/etna/pull/875))
 - 
 - Implementation of PatchTS model ([#1277](https://github.com/tinkoff-ai/etna/pull/1277))
+- Add `quickstart` notebook, add `mechanics_of_forecasting` notebook ([#1343](https://github.com/tinkoff-ai/etna/pull/1343))
 
 ### Changed
 - 
-- 
+- Add installation page and notes about extensions into documentation of public classes ([#1339](https://github.com/tinkoff-ai/etna/pull/1339))
 - Unify errors, warnings and checks in models ([#1312](https://github.com/tinkoff-ai/etna/pull/1312))
-- 
+- Merge User Guide and API sections in documentation, limit classes to show in API section ([#1324](https://github.com/tinkoff-ai/etna/pull/1324))
+- Unify example notebooks, rerun example notebooks ([#1330](https://github.com/tinkoff-ai/etna/pull/1330))
+- Rework `get_started` notebook ([#1343](https://github.com/tinkoff-ai/etna/pull/1343))
 
 ### Fixed
 - 
-- 
+- Rendering table of contents in notebooks ([#1343](https://github.com/tinkoff-ai/etna/pull/1343))
 - 
 - `mrmr` feature selection working with categoricals ([#1311](https://github.com/tinkoff-ai/etna/pull/1311))
 - Fix version of `statsforecast` to 1.4 to avoid dependency conflicts during installation ([#1313](https://github.com/tinkoff-ai/etna/pull/1313))

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -12,13 +12,13 @@ Every good PR usually consists of:
 
 ## Step-by-step guide
 
-### Before the PR
+### 1. Before the PR
 Please ensure that you have read the following docs:
-- [changelog](https://github.com/tinkoff-ai/etna/blob/master/CHANGELOG.md)
 - [documentation](https://etna-docs.netlify.app/)
 - [tutorials](https://github.com/tinkoff-ai/etna/tree/master/examples)
+- [changelog](https://github.com/tinkoff-ai/etna/blob/master/CHANGELOG.md)
 
-### Setting up your development environment
+### 2. Setting up your development environment
 
 Before writing any code it is useful to set up a development environment.
 1. Clone etna library to some folder and go inside:
@@ -35,19 +35,24 @@ poetry install -E all-dev
 poetry shell
 ```
 
-To connect virtual environment interpreter to IDE use `which python` command.
+To connect virtual environment interpreter to IDE the `which python` command can be useful.
+
+### 3. Suggesting a feature (optional)
 
-### New feature
+This is an optional step, you could skip it if you want to take some of the existing tasks.
 
 1. Make an issue with your feature description;
 2. We shall discuss the design and its implementation details;
 3. Once we agree that the plan looks good, go ahead and implement it.
 
-### Bugfix
+### 4. Choosing a task
 
 1. Goto [GitHub issues](https://github.com/tinkoff-ai/etna/issues);
-2. Pick an issue and comment on the task that you want to work on this feature;
-3. If you need more context on a specific issue, please ask, and we will discuss the details.
+2. Pick an issue with status "Todo" on a [board](https://github.com/orgs/tinkoff-ai/projects/2)
+3. Leave a comment in the issue that you want to work on this task;
+4. If you need more context on a specific issue, please ask, and we will discuss the details.
+
+### 5. Doing a task
 
 You can also join our [ETNA Community telegram chat](https://t.me/etna_support) to make it easier to discuss.
 Once you finish implementing a feature or bugfix, please send a Pull Request.
@@ -56,62 +61,28 @@ If you are not familiar with creating a Pull Request, here are some guides:
 - [Creating a pull request](https://help.github.com/articles/creating-a-pull-request/);
 - [Creating a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
 
-### Tests
+### 6. Writing tests
 
-Do not forget to check that your code passes the unit tests. 
+Do not forget to check that your code passes the unit tests.
 ```bash
-poetry install -E tests
-
 pytest tests -v
 pytest etna -v --doctest-modules
 ```
 
 ETNA uses the [`black`](https://github.com/psf/black) and [`flake8`](https://github.com/pycqa/flake8) with several plugins 
 for coding style checks as well as [`mypy`](https://github.com/python/mypy) for type checks, and you must ensure that your code follows it. 
 ```bash
-poetry install -E style
-
 make format
 ```
 
 If any of checks fails, the CI will fail and your Pull Request won't be merged.
 
-### Documentation
+### 7. Writing a documentation
 
 ETNA uses [Numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html) for formatting docstrings. 
 The documentation is written in ReST.
 Length of a line inside docstrings block must be limited to 100 characters to fit into Jupyter documentation popups.
 
-You could check the docs with:
-```bash
-cp examples/*.ipynb docs/source/tutorials
-cd docs
-make clean
-make html
-```
-
-Now you could open them into your browser, for example with
-```bash
-open ./build/html/index.html
-```
-
-If you have some issues with building docs - please make sure that you installed the required packages.
-
-```bash
-poetry install -E docs
-```
-You also may need to install pandoc package ([pandoc installation guide](https://pandoc.org/installing.html)):
-```bash
-# Ubuntu
-apt-get update && apt-get install -y pandoc
-
-# Mac OS
-brew install pandoc
-
-#Windows
-choco install pandoc
-```
-
 During creation of Pull Request make sure that your documentation looks good, check:
 1. `Parameters` and `Returns` sections have correct names and types;
 2. Sections should be
@@ -129,3 +100,42 @@ Useful links:
 3. [ReST Cross-referencing Python objects](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects)
 4. [Matplotlib Cheetsheet](https://matplotlib.org/sampledoc/cheatsheet.html)
 5. [Sklearn example](https://github.com/scikit-learn/scikit-learn/blob/37ac6788c/sklearn/linear_model/_ridge.py#L321)
+
+The simplest way to check how documentation is rendered is to make a pull request. 
+CI will build it, publish and attach a link to the pull request.
+
+#### 7.1 Adding tutorials (optional)
+
+If you are going to add a jupyter notebook tutorial:
+1. Add the notebook into `examples` folder with its prepended number.
+2. Add "launch binder" button to the notebook.
+3. Add "Table of contents" for headings of the levels 2 and 3.
+4. Install extensions that are necessary for this notebook to run.
+5. Add imports that are unrelated to the topic of the tutorial at the very top.
+6. Add new notebook with its table of contents to the `examples/README.md`
+7. Add new notebook with to the `README.md`
+
+#### 7.2 Building locally (optional)
+
+You can also build the documentation locally.
+Before building the documentation you may need to install a pandoc package ([pandoc installation guide](https://pandoc.org/installing.html)):
+```bash
+# Ubuntu
+apt-get update && apt-get install -y pandoc
+
+# Mac OS
+brew install pandoc
+
+# Windows
+choco install pandoc
+```
+
+After that, you can try to build the docs with:
+```bash
+cd docs
+make build-docs
+```
+
+You could check the result in your browser by opening `build/html/index.html` file.
+
+If you have some issues with building docs - please make sure that you installed the required packages.
diff --git a/Makefile b/Makefile
@@ -30,6 +30,7 @@ imported-deps-check:
 
 notebooks-check:
  black --check examples/*.ipynb
+ nbqa isort --sl -c examples/
 
 format-examples:
  isort --sl examples/**/*.py
@@ -38,6 +39,7 @@ format-examples:
 format:
  isort --skip etna/libs --sl etna/
  isort --skip etna/libs --sl tests/
+ nbqa isort --sl examples/
  black etna/
  black tests/
  black examples/*.ipynb