############
Development
############

About library
=============================
We use `OpenAPI (Swagger) <https://swagger.io/docs/specification/about/>`__  and `swagger-codegen <https://github.com/swagger-api/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**

.. list-table::
   :widths: 5 15 15 70
   :header-rows: 1

   * - 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 <https://teamcity.example.com/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) <https://habr.com/post/180213/>`__

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 <https://github.com/devopshq/teamcity/compare/master...develop>`__
 + Request review and pull it
 + Bump ``VERSION`` in `setup.py <https://github.com/devopshq/teamcity/blob/develop/setup.py#L6>`__ on ``develop``-branch after success pull.