Skip to content

Commit dd1c39f

Browse files
andydemidandydemid
committed
Merge branch 'PYT-846' into 'develop'
PYT-846: Python SDK documentation Closes PYT-880 See merge request SOLO-band/python-sdk!102
2 parents 8396872 + 28b2624 commit dd1c39f

Some content is hidden

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

56 files changed

+9236
-743
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,3 +134,6 @@ dmypy.json
134134
.DS_Store
135135
.AppleDouble
136136
.LSOverride
137+
138+
### Documentation ###
139+
docs/syntax_folder/

‎.gitlab-ci.yml

Lines changed: 55 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,27 +3,40 @@ default:
33
tags:
44
- docker
55
- ubuntu
6-
before_script:
7-
- pip install --upgrade pip
8-
- pip install .[dev]
6+
7+
include:
8+
- project: "infra/ci-templates"
9+
ref: "master"
10+
file:
11+
- rules.yml
12+
- vault_auth.yml
13+
- build.yml
14+
- deploy_k8s.yml
15+
- deploy_k8s/envs/deploy_kubesolo_k8s.yml
16+
- deploy_k8s/envs/deploy_aws_k8s.yml
917

1018
stages:
1119
- test
1220
- build
1321
- publish
22+
- deploy
1423

1524
test:
1625
stage: test
1726
rules:
1827
- when: manual
28+
before_script:
29+
- pip install --upgrade pip
30+
- pip install .[dev]
1931
script:
2032
- pre-commit run --all-files
2133
- pytest tests/main --verbosity=1
2234

2335
build:
2436
stage: build
25-
rules:
26-
- when: on_success
37+
before_script:
38+
- pip install --upgrade pip
39+
- pip install .[dev]
2740
script:
2841
- python -m build
2942
artifacts:
@@ -39,5 +52,42 @@ publish:
3952
variables:
4053
TWINE_USERNAME: __token__
4154
TWINE_PASSWORD: $PYPI_TOKEN
55+
before_script:
56+
- pip install --upgrade pip
57+
- pip install .[dev]
4258
script:
4359
- twine upload dist/* --verbose
60+
61+
build_python_docs:
62+
extends:
63+
- .build_docker_template
64+
variables:
65+
BUILD_CONTEXT: ${CI_PROJECT_DIR}
66+
DOCKER_FILE: ${CI_PROJECT_DIR}/docs/Dockerfile
67+
DOCKER_REPO: ${CI_REGISTRY_IMAGE}/python-docs
68+
rules:
69+
- !reference [.rules_template, web_manual]
70+
71+
.deploy_variables:
72+
variables:
73+
KUBERNETES_NAMESPACE_OVERWRITE: python-docs
74+
K8S_DEPLOYMENT_DIR: rogii/python-docs
75+
DEPLOY_COMPONENTS: "python-docs"
76+
IMAGE_NAME: ${CI_REGISTRY_IMAGE}/python-docs
77+
needs:
78+
- build_python_docs
79+
rules:
80+
- !reference [.rules_template, web_manual]
81+
82+
deploy_awsstaging_k8s:
83+
rules: [when: never]
84+
85+
deploy_kubesolo_k8s:
86+
environment:
87+
name: kubesolo
88+
url: https://python.rogii.net
89+
90+
deploy_awsprod_k8s:
91+
environment:
92+
name: awsprod
93+
url: https://python.solo.cloud

‎.gitlab/CODEOWNERS

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[SRE] @dev-team/sre
2+
.gitlab-ci.yml
3+
/.gitlab/
4+
/docs/Dockerfile

‎docs/.env.example

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
DOCS_DOMAIN=python.solo.cloud
2+
PYTHONPATH=/app/docs

‎docs/Dockerfile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
FROM python:3.10-slim AS builder
2+
3+
WORKDIR /app
4+
ENV IN_DOCKER=true \
5+
PYTHONPATH=/app/docs:$PYTHONPATH
6+
7+
COPY docs/requirements.txt .
8+
RUN pip install --no-cache-dir -r requirements.txt
9+
10+
COPY docs/docs /app/docs
11+
12+
COPY src /app/src
13+
14+
RUN sphinx-build -b html /app/docs /app/syntax_folder
15+
16+
FROM public.ecr.aws/rogii/nginx:mainline
17+
18+
COPY --from=builder /app/syntax_folder /usr/share/nginx/html
19+
20+
COPY docs/nginx/default.conf /etc/nginx/conf.d/default.conf

‎docs/README.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## Документации Python SDK
2+
Используется Sphinx + Sphinx AutoAPI.
3+
4+
### Как обновить артефакты документации
5+
При добавлении нового файла с документацией объектов в `\src` необходимо добавить его руками в `\docs\_templates\autoapi\index.rst` и в `\docs\custom_stuff\python_doc_names.py`
6+
7+
Документация создаётся в докере. Для создания:
8+
```
9+
добавить .env в docs
10+
docker-compose build --no-cache
11+
docker-compose up -d
12+
```
13+
14+
15+
### Полезные ссылки:
16+
- https://www.sphinx-doc.org/
17+
- https://sphinx-autoapi.readthedocs.io/
18+
- https://bylr.info/articles/2022/05/10/api-doc-with-sphinx-autoapi/
19+
- https://www.aahilm.com/blog/documenting-large-projects-with-sphinx
20+
- https://sphinx-intro-tutorial.readthedocs.io/en/latest/
21+
- https://software.belle2.org/sphinx/light-2205-abys/framework/doc/atend-doctools.html

‎docs/docker-compose.yml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
services:
2+
sdk-docs:
3+
build:
4+
context: ..
5+
dockerfile: docs/Dockerfile
6+
args:
7+
- PYTHONPATH=${PYTHONPATH}
8+
ports:
9+
- "80:80"
10+
container_name: sdk-docs
11+
environment:
12+
- DOCS_DOMAIN=${DOCS_DOMAIN}

‎docs/docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/docs/_static/custom.css

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
p{
2+
text-align: justify;
3+
}
4+
5+
.sidebar-brand-text{
6+
text-align: center;
7+
}
8+
9+
a:visited {
10+
color: var(--color-link);
11+
}
12+
13+
.sidebar-logo {
14+
width: 100%;
15+
height: auto; /* Сохраняет пропорции SVG */
16+
display: block; /* Убирает лишнее пространство снизу SVG */
17+
}
18+
19+
20+
.sidebar-drawer {
21+
width: calc(50% - 32em);
22+
}
23+
24+
.content {
25+
width: 59em;
26+
}
27+
28+
table.summarytable {
29+
width: 100%;
30+
}
31+
32+
table.summarytable tr td:first-child, /* Для ячеек данных */
33+
table.summarytable tr th:first-child { /* Для ячеек заголовков */
34+
width: 270px;
35+
}
36+
37+
.caption-text {
38+
font-size: 160%;
39+
font-weight: bold;
40+
}
41+
42+
span.summarylabel-method, span.summarylabel-property, span.summarylabel-attribute{
43+
color: var(--color-background-secondary);
44+
font-size: 70%;
45+
padding-left: 2px;
46+
padding-right: 2px;
47+
border-radius: 3px;
48+
vertical-align: 15%;
49+
padding-bottom: 2px;
50+
filter: opacity(40%);
51+
}
52+
53+
span.summarylabel-method {
54+
background-color: #0B9100;
55+
}
56+
57+
span.summarylabel-property {
58+
background-color: #FF6C00;
59+
}
60+
61+
span.summarylabel-attribute {
62+
background-color: #28ccd8;
63+
}
64+
65+
ul {
66+
padding: 0;
67+
margin: 0;
68+
list-style: none;
69+
}
70+
71+
.sidebar-tree ul{
72+
margin-top: 10px;
73+
margin-bottom: 10px;
74+
}
75+
76+
.module-list li {
77+
margin-top: 10px;
78+
margin-bottom: 10px;
79+
}
80+
81+
.title-list ul{
82+
padding-left: 20px;
83+
margin-top: 5px;
84+
margin-bottom: 5px;
85+
}
86+
87+
.title-item {
88+
padding-left: 20px;
89+
font-size: 15px;
90+
margin-top: 20px;
91+
margin-bottom: 20px;
92+
}
93+
94+
.class-list {
95+
margin-left: 35px;
96+
margin-top: 50px;
97+
margin-bottom: 50px;
98+
}
99+
100+
.class-item {
101+
margin-left: 40px;
102+
font-size: 15px;
103+
margin-top: 40px;
104+
margin-bottom: 40px;
105+
}

‎docs/docs/_static/favicon.svg

Lines changed: 17 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)