update doc and docstring

docs-static/usage.md

@@ -1,16 +1,105 @@
 # Usage
 
-## Pulvinar dolor
-Donec dapibus est fermentum justo volutpat condimentum. Integer quis nunc neque. Donec dictum vehicula justo, in facilisis ex tincidunt in. 
-Vivamus sollicitudin sem dui, id mollis orci facilisis ut. Proin sed pulvinar dolor. Donec volutpat commodo urna imperdiet pulvinar. Fusce eget aliquam risus. 
-Vivamus viverra luctus ex, in finibus mi. Nullam elementum dapibus mollis. Ut suscipit volutpat ex, quis feugiat lacus consectetur eu. 
+## Installation
+From master repository:
 
-## Condimentum faucibus
-Quisque auctor egestas sem, luctus suscipit ex maximus vitae. Duis facilisis augue et condimentum faucibus. 
-Donec cursus, enim a sagittis egestas, lectus lorem eleifend libero, at tincidunt leo magna at libero. 
-Nunc eros velit, suscipit luctus tempor vel, finibus et est. Curabitur efficitur pretium pulvinar. 
-Donec urna lectus, vulputate quis turpis sed, placerat congue urna. Phasellus aliquet fermentum quam, non auctor elit porta nec. Morbi eu ligula at nisl ultricies condimentum vitae id ante. 
+    python -m pip install git+https://chacha.ddns.net/gitea/chacha/pygitversionhelper.git@master
 
-## Aliquam lacinia
-In volutpat lorem ex, et fringilla nibh faucibus quis. Mauris et arcu elementum, auctor dui vitae, egestas arcu. Duis sit amet aliquam quam. 
-Phasellus a odio turpis. Etiam tristique mi eu enim varius, eget facilisis est vestibulum. Aliquam lacinia nec purus sed luctus. Cras at laoreet erat. 
+From local .whl file:
+
+    python -m pip install pygitversionhelper-<VERSION>-py3-none-any.whl
+
+From public repository:
+
+    TBD
+
+## Import in your project
+Add this line on the top of your python script:
+
+    #from pygitversionhelper import gitversionhelper
+
+(optionnal)If you need to catch exception from this module:
+
+    #from pygitversionhelper import gitversionhelperException
+    
+## Basic API
+All the API commands are static and so it is not needed to create instantiate any object.
+
+They are all executed in the current active directory.
+
+One easy way to change directory:
+
+    import os
+    os.chdir("<YOUR DIRECTORY>")
+
+### sublib: repository 
+To check if a repository is dirty:
+
+    if gitversionhelper.repository.isDirty():
+        print("repository is dirty")
+
+### sublib: tag 
+List all tags (default to taggerdate order):
+
+    for tag in gitversionhelper.tag.getTags():
+        print(f"found tag: {tag}")
+        
+List all tags (using git refname order):
+
+    for tag in gitversionhelper.tag.getTags("v:refname"):
+        print(f"found tag: {tag}")
+
+Get the last tag:
+
+    print(f"most recent repository tag: {gitversionhelper.tag.getLastTag()}")
+    
+Get the last tag (only on same branch):
+
+    print(f"most recent repository tag: {gitversionhelper.tag.getLastTag(same_branch=True)}")
+
+
+Get the distance from HEAD to last tag:
+
+    print(f"number of commit since last tag: {gitversionhelper.tag.getDistanceFromTag()}")
+
+Get the distance from HEAD to last tag (only on same branch):
+
+    print(f"number of commit since last tag: {gitversionhelper.tag.getDistanceFromTag(same_branch=True)}")
+    
+### sublib: version 
+Get the last found version in the repository (return MetaVersion object):
+
+    print(f"most recent repository version: {gitversionhelper.tag.getLastVersion()}")
+    
+Get the last found version in the repository (return formated string):
+
+    print(f"most recent repository version: {gitversionhelper.tag.getLastVersion(formated_output=True)}")
+
+Others kwargs available to this function:
+    - version_std: string to force a version standard for rendering ("PEP440" or "SemVer")
+    - same_branch: boolean to force searching on same branch
+    - ignore_unknown_tags: boolean to allow unknown tag to be ignored
+
+Get the current version of the repository, including bumped one if the last one is not tagged (return MetaVersion object):
+
+    print(f"most recent repository version: {gitversionhelper.tag.getCurrentVersion()}")
+    
+kwargs available to this function:
+    - All same args as getLastVersion()
+    - bump_type: if version need to be pump, allow to configure next release update type: major, minor, patch, dev
+    - bump_dev_strategy: if bump_type is dev, allow to choose dev update strategy: post, pre-patch, pre-minor, pre-major
+
+A version object can also be manually formated:
+
+    _version = gitversionhelper.tag.getCurrentVersion()
+    _version.doFormatVersion()
+    #or
+    gitversionhelper.version.doFormatVersion(_version)
+
+kwargs available to those function:
+    - output_format: string to choose a rendering format ("Auto","PEP440" or "SemVer")
+
+##Limitations
+- MultiThreading and async behavior is not tested.
+- Multiple tag on the same commit is not supported.
+- Branch filter when searching for a version is only tested with -no-ff strategy