Fixes in docs

barseghyanartur · Nov 17, 2019 · 060c8ac · 060c8ac
1 parent aa27091
commit 060c8ac
Showing 1 changed file with 43 additions and 154 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -27,136 +27,76 @@ Prerequisites
 =============
 - Python 3.6, 3.7, 3.8 and PyPy
 
-Use cases and basic concepts
-============================
-If the following applies to you, ``matyan`` could help:
-
-- Project releases (tags) are numbered according to the
-  `semantic versioning <https://semver.org/>`_ or
-  `sequence based identifiers <http://en.wikipedia.org/wiki/Software_versioning#Sequence-based_identifiers>`_.
-- Project follows the DTAP.
-- Testing, acceptance and production branches (hereafter referred as TAP
-  branches) are protected.
-- Direct commits to TAP branches are forbidden.
-- All commits to TAP branches are made by pull requests.
-- JIRA (or a similar tool) is used for handing project tickets.
-- Pull requests are merged using GitHub or BitBucket web interface.
-
-Sample use-case
----------------
-The use-case
-~~~~~~~~~~~~
-- JIRA is used for issues.
-- All commits are prefixed with ID of the JIRA issue: for example, `MSFT-1234`
-  or `NVDA-1234` (where first four letters identify the client commit was done
-  for, it's pattern).
-- There are 3 main (protected) branches: `dev`, `staging`, `master`.
-  Direct commits to any of the 3 are forbidden. Any feature/bugfix comes via
-  merge request.
-- All branches do have meaningful prefixes. Example,
-  `feature/MSFT-1234-Title-of-the-issue` or
-  `bugfix/MSFT-1236-prevent-duplicate-postal-codes`.
-- Release flow is `dev` -> `staging` -> `master`.
-
-Sample commits
-~~~~~~~~~~~~~~
-Consider the following commits into the dev branch:
-
-*branch: bugfix/MSFT-1240-LinkedIn-authentication-failing*
-
-- MSFT-1240 Fix package configuration.
-- MSFT-1240 Update authentication pipeline.
-
-*branch: deprecation/MSFT-1239-Deprecate-Python2*
-
-- MSFT-1239 Deprecate Python2.
-- MSFT-1238 Add initial MyPY setup.
-
-*branch: feature/MSFT-1238-Token-authentication*
-
-- MSFT-1238 Implement token authentication.
-- MSFT-1238 Update authentication docs.
-
-*branch: feature/MSFT-1237-Improve-document-sharing*
-
-- MSFT-1237 Improve document sharing. Add option to share via GDrive.
-
-*branch: bugfix/MSFT-1236-prevent-duplicate-postal-codes*
-
-- MSFT-1236 Normalise postal codes for German addresses.
-- MSFT-1236 Normalise postal codes for US addresses.
-- MSFT-1236 Make postal code field unique for the country.
-
-*branch: deprecation/MSFT-1235-deprecate-old-api*
-
-- MSFT-1235 Deprecate API v 2.0.
-- MSFT-1235 Update docs.
+Documentation
+=============
+Documentation is available on `Read the Docs
+<http://matyan.readthedocs.io/>`_.
 
-*branch: feature/MSFT-1234-car-type-suggester*
+Installation
+============
+Latest stable version on PyPI:
 
-- MSFT-1234 Initial car type suggester implementation.
-- MSFT-1234 Add insurance amount indication based on car weight.
+.. code-block:: sh
 
-Sample releases
-~~~~~~~~~~~~~~~
-All commits have been finally merged into master.
+    pip install matyan
 
-Releases have been made in the following way:
+Usage
+=====
+See `Basic concepts <https://matyan.readthedocs.io/en/latest/basic_concepts.html>`_
+section to get impression on possible commit methodology and assumptions taken.
 
-*0.1*
+**Generate changelog:**
 
-- Merged issues MSFT-1234, MSFT-1235 and MSFT-1236
+.. code-block:: sh
 
-*0.2*
+    generate-changelog
 
-- Merged issues MSFT-1237 and MSFT-1238
+**Generate changelog skipping orphaned commits:**
 
-*Yet unreleased features/branches*
+In some cases you only want to show what has been done with tickets and skip
+all non-ticket related commits.
 
-- MSFT-1239 and
+.. code-block:: sh
 
-Sample changelog output
------------------------
-The generated change log would look as follows:
+    generate-changelog --no-other
 
-.. code-block:: text
+**Generate changelog between two releases:**
 
-    ### 0.2
+In some cases you only want to show what has been done since last release.
+The following example would generate changelog since version 0.0.1 to
+version 0.0.3.
 
-    **Features**
+.. code-block:: sh
 
-    *MSFT-1238 Token-authentication*
+    generate-changelog 0.0.1..0.0.3
 
-    - Implement token authentication.
-    - Update authentication docs.
+**Generate changelog between two branches:**
 
-    *MSFT-1237 Improve document sharing*
+In some cases you only want to show what has been done since last release.
+The following example would generate changelog since version 0.0.1 to
+version 0.0.3.
 
-    - Improve document sharing. Add option to share via GDrive.
+.. code-block:: sh
 
-    ### 0.1
+    generate-changelog master..dev
 
-    **Bugfixes**
+**Generate changelog with releases info shown**
 
-    *MSFT-1236 Prevent duplicate postal codes*
+.. code-block:: sh
 
-    - Normalise postal codes for German addresses.
-    - Normalise postal codes for US addresses.
-    - Make postal code field unique for the country.
+    generate-changelog --show-releases
 
-    **Deprecations**
+**Generate changelog between releases with releases info shown**
 
-    *MSFT-1235 Deprecate old api*
+.. code-block:: sh
 
-    - Deprecate API v 2.0.
-    - Update docs.
+    generate-changelog 0.0.1..0.0.3 --show-releases
 
-    **Features**
+**Generate changelog between branches with releases info shown**
 
-    *MSFT-1234 Car type suggester*
+.. code-block:: sh
 
-    - Initial car type suggester implementation.
-    - Add insurance amount indication based on car weight.
+    generate-changelog master..dev --show-releases
 
 Configuration
 =============
@@ -206,58 +146,6 @@ Create initial config file
 
     matyan-create-config
 
-Documentation
-=============
-Documentation is available on `Read the Docs
-<http://matyan.readthedocs.io/>`_.
-
-Installation
-============
-Latest stable version on PyPI:
-
-.. code-block:: sh
-
-    pip install matyan
-
-Usage
-=====
-**Generate changelog:**
-
-.. code-block:: sh
-
-    generate-changelog
-
-**Generate changelog skipping orphaned commits:**
-
-In some cases you only want to show what has been done with tickets and skip
-all non-ticket related commits.
-
-.. code-block:: sh
-
-    generate-changelog --no-other
-
-**Generate changelog between two releases:**
-
-In some cases you only want to show what has been done since last release.
-The following example would generate changelog since version 0.0.1 to
-version 0.0.3.
-
-.. code-block:: sh
-
-    generate-changelog 0.0.1..0.0.3
-
-**Generate changelog with releases info shown**
-
-.. code-block:: sh
-
-    generate-changelog --show-releases
-
-**Generate changelog between releases with releases info shown**
-
-.. code-block:: sh
-
-    generate-changelog 0.0.1..0.0.3 --show-releases
-
 Testing
 =======
 Simply type:
@@ -328,6 +216,7 @@ Contents:
    :maxdepth: 20
 
    index
+   basic_concepts
    changelog
    matyan