Development¶

About library¶

We use OpenAPI (Swagger) and swagger-codegen to generate most of code. But swagger generate not user-friendly libraries, we extend them manually. If you want fix some bug or realize some feature, please read this before.

Swagger or not swagger¶

You want to change a file - look carefully at the table, maybe it was generated automatically and it needs to be expanded using the template. But if you want to make changes really only in one class or documentation - see the column Custom extenstion

Type	Files	Template	Custom extension
Code	`dohq_teamcity/models/*`	`swagger/template/model.mustache`	You can extend Model in `dohq_teamcity/custom/models.py` or `dohq_teamcity/custom/base_model.py` for all object
Code	`dohq_teamcity/api/*`	`swagger/template/api.mustache`	You can extend API in `dohq_teamcity/custom/api.py`
Docs	`docs-sphinx/swagger/models*`	`swagger/template/model_doc.mustache`	If you want write some usefull examples - change a file in the directory `docs-sphinx/examples/models`
Docs	`docs-sphinx/swagger/api*`	`swagger/template/model_doc.mustache`	If you want write some usefull examples - change a file in the directory `docs-sphinx/examples/api`
Other part	You can change as you want :)

Run swagger¶

If you want run swagger-codegen (after change some mustache file, for example), use it:

# Install java before :)

 bash ./swagger.sh

If you have new swagger.json from TeamCity server (you can find it on page https://teamcity.ptsecurity.ru/app/rest/swagger.json) , replace you fqdn in the file to teamcity.example.com, place it in swagger/swagger.json and run:

bash ./swagger.sh

Documentation¶

Some part of documentation is autogenerated. Please see above table and ensure what type of file you want change.

Build and view¶

We use sphinx to build docs:

cd docs-sphinx
make html
# open ./docs-sphinx/_build/html/index.html on your browser
start ./_build/html/index.html # Windows

Publish¶

For repositories admin:

All documentation saved in docs-folder on branches.

We use gh-pages as source for publishing on github pages.

Read example how it work on habr.com (Russian)

Run this script to publish new html on https://devopshq.github.io/teamcity/

cd docs
bash ./publish-gh-pages.sh

Create release¶

If you want release this library, reproduce this steps:

Create pull request develop <= master
Request review and pull it
Bump VERSION in setup.py on develop-branch after success pull.