Done

README.md

@@ -4,28 +4,118 @@ Service to get up-to-date information about countries and cities.
 
 ## Requirements:
 
+Install the appropriate software:
+
+1. [Docker Desktop](https://www.docker.com).
+2. [Git](https://github.com/git-guides/install-git).
+3. [PyCharm](https://www.jetbrains.com/ru-ru/pycharm/download) (optional).
+
+## Quick start
+1. `cp .env.sample .env`
+2. `docker compose up --build`
+3. `docker exec -it countries-informer-app bash`
+4. `python manage.py migrate --fake sessions zero`
+   `python manage.py showmigrations
+    sessions
+     [ ] 0001_initial`
+   `python manage.py migrate --fake-initial`
 
 
 ## Installation
 
+Clone the repository to your computer:
+```bash
+git clone https://github.com/DmitryZubarev/HSE-Python-CountriesInformer.git
+```
 
+1. To configure the application copy `.env.sample` into `.env` file:
+    ```shell
+    cp .env.sample .env
+    ```
 
-## Usage
+    This file contains environment variables that will share their values across the application.
+    The sample file (`.env.sample`) contains a set of variables with default values. 
+    So it can be configured depending on the environment.
+
+2. Build the container using Docker Compose:
+    ```shell
+    docker compose build
+    ```
+    This command should be run from the root directory where `Dockerfile` is located.
+    You also need to build the docker container again in case if you have updated `requirements.txt`.
 
+3. Now it is possible to run the project inside the Docker container:
+    ```shell
+    docker compose up
+    ```
+   When containers are up server starts at [http://0.0.0.0:8020](http://0.0.0.0:8020). You can open it in your browser.
+
+
+## Usage
 
+1. To manage your api you need to add superuser.
+    Connect to the application Docker-container (if you are outside the container):
+    ```shell
+    docker compose exec app bash
+    ```
+   Create superuser:
+    ```shell
+    ./manage.py createsuperuser
+    ```
+2. Go to [http://0.0.0.0:8020/admin](http://0.0.0.0:8020/admin) and manage your database.
 
 ## Automation commands
 
+The project contains a special `Makefile` that provides shortcuts for a set of commands:
+1. Build the Docker container:
+    ```shell
+    make build
+    ```
 
+2. Generate Sphinx documentation run:
+    ```shell
+    make docs-html
+    ```
+
+3. Autoformat source code:
+    ```shell
+    make format
+    ```
+
+4. Static analysis (linters):
+    ```shell
+    make lint
+    ```
+
+5. Autotests:
+    ```shell
+    make test
+    ```
+
+6. Run autoformat, linters and tests in one command:
+    ```shell
+    make all
+    ```
+
+Run these commands from the source directory where `Makefile` is located.
 
 ## Documentation
 
+The project integrated with the [Sphinx](https://www.sphinx-doc.org/en/master/) documentation engine. 
+It allows the creation of documentation from source code. 
+So the source code should contain docstrings in [reStructuredText](https://docutils.sourceforge.io/rst.html) format.
+
+To create HTML documentation run this command from the source directory where `Makefile` is located:
+```shell
+make docs-html
+```
 
+After generation documentation can be opened from a file `docs/build/html/index.html`.
 
 ## Contributing
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
 
 Please make sure to update tests as appropriate.
 
 ## License
-[MIT](https://choosealicense.com/licenses/mit/)
+[MIT](https://choosealicense.com/licenses/mit/)

docs/source/code.rst

@@ -1,5 +1,94 @@
+Документация к исходному коду
+=============================
+
 .. autosummary::
     :toctree: _autosummary
     :recursive:
 
     app
+
+.. index:: view, base
+
+Geo service
+===========
+.. toctree::
+   :maxdepth: 2
+   :caption: Содержимое:
+
+Клиенты
+-------
+Страны и города
+^^^^^^^^^^^^^^^
+.. automodule:: geo.clients.geo
+   :members:
+
+Валюты
+^^^^^^
+.. automodule:: geo.clients.currency
+   :members:
+
+Погода
+^^^^^^
+.. automodule:: geo.clients.weather
+   :members:
+
+Схемы
+^^^^^
+.. automodule:: geo.clients.schemas
+   :members:
+
+Сервисы
+-------
+
+Страны
+^^^^^^^^^^^^^^^
+.. automodule:: geo.services.country
+   :members:
+
+Города
+^^^^^^^^^^^^^^^
+.. automodule:: geo.services.city
+   :members:
+
+Валюты
+^^^^^^
+.. automodule:: geo.services.currency
+   :members:
+
+Погода
+^^^^^^
+.. automodule:: geo.services.weather
+   :members:
+
+Схемы
+^^^^^
+.. automodule:: geo.services.schemas
+   :members:
+
+Views
+------
+.. automodule:: geo.views
+   :members:
+
+.. index:: view, base
+
+News service
+============
+.. toctree::
+   :maxdepth: 2
+   :caption: Содержимое:
+
+Клиент
+-------
+.. automodule:: news.clients.news
+   :members:
+
+Сервис
+-------
+.. automodule:: news.services.news
+   :members:
+
+Views
+------
+.. automodule:: news.views
+   :members:

docs/source/index.rst

@@ -1,3 +1,9 @@
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   API reference <code>
+
 Портфолио
 =========
 
@@ -6,29 +12,131 @@
 Зависимости
 ===========
 
+1. Фреймворк
+Django>=4.0.7,<4.1.0
+djangorestframework>=3.14.0,<3.15.0
+
+2. Генерация Swagger
+drf-yasg>=1.21.4,<1.22.0
+
+3. Работа с переменными окружения
+django-environ>=0.9.0,<0.10.0
+
+4. Отладчик для Django
+django-debug-toolbar>=3.6.0,<3.7.0
+
+5. Адаптер для подключения к PostgreSQL
+psycopg2-binary>=2.9.3,<2.10.0
+
+6. Документация
+Sphinx>=5.1.1,<5.2.0
+sphinx-rtd-theme>=1.0.0,<2.0.0
+
+7. Статический анализ кода (линтеры)
+isort>=5.10.1,<5.11.0
+flake8-django>=1.1.5,<1.2.0
+pylint-django>=2.5.3,<2.6.0
+django-stubs[compatible-mypy]>=1.12.0,<1.13.0
+
+8. Автоматическое форматирование кода
+black>=22.8.0,<22.9.0
+
+9. Redis
+redis>=4.3.4,<4.4.0
+
+10. Распределенная очередь задач
+celery>=5.2.7,<5.3.0
+django-celery-beat>=2.3.0,<2.4.0
+
+11. Работа с RabbitMQ
+pika>=1.3.1,<1.4.0
+
+12. Работа с HTTP-запросами
+httpx>=0.23.0,<0.24.0
+
+13. DTO и валидация данных
+pydantic>=1.10.2,<1.11.0
 
 
 Установка
 =========
 
+Установите требуемое ПО:
+
+1. Docker для контейнеризации – |link_docker|
+
+.. |link_docker| raw:: html
+
+   <a href="https://www.docker.com" target="_blank">Docker Desktop</a>
+
+2. Для работы с системой контроля версий – |link_git|
+
+.. |link_git| raw:: html
+
+   <a href="https://github.com/git-guides/install-git" target="_blank">Git</a>
+
+3. IDE для работы с исходным кодом – |link_pycharm|
+
+.. |link_pycharm| raw:: html
+
+    <a href="https://www.jetbrains.com/ru-ru/pycharm/download" target="_blank">PyCharm</a>
+
+Клонируйте репозиторий проекта в свою рабочую директорию:
+
+    .. code-block:: console
+        git clone https://github.com/miamib34ch/HSE-Python-CountriesInformer.git
 
 
 Использование
 =============
 
+1. Чтобы управлять вашим API, вам необходимо добавить суперпользователя. Подключитесь к контейнеру Docker-приложения (если вы находитесь вне контейнера):
+
+    .. code-block:: console
+        docker-compose exec app bash
+
 
+2. Создайте суперпользователя:
 
-Работа с базой данных
----------------------
+    .. code-block:: console
+        ./manage.py createsuperuser
 
+3. Перейдите по адресу http://0.0.0.0:8020/admin и управляйте вашей базой данных.
 
 
 Автоматизация
 =============
 
+Проект содержит специальный файл Makefile, который предоставляет ярлыки для выполнения определенного набора команд:
+
+Построить Docker-контейнер:
+
+    .. code-block:: console
+        make build
+
+Сгенерировать документацию Sphinx:
+
+    .. code-block:: console
+        make docs-html
+
+Автоформатирование исходного кода:
+
+    .. code-block:: console
+        make format
+
+Статический анализ (линтеры):
+
+    .. code-block:: console
+        make lint
+
+Автотесты:
 
+    .. code-block:: console
+        make test
 
-Тестирование
-============
+Выполнить автоформатирование, статический анализ и тесты одной командой:
 
+    .. code-block:: console
+        make all
 
+Запустите эти команды из директории с исходным кодом, где расположен файл Makefile.