update doc

Max Zhenzhera · Max Zhenzhera · commit cf63e2c1935b · 2021-05-22T12:40:37.000+03:00
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,13 +1,13 @@
-.. python-FreeDictionaryApi documentation master file, created by
+.. python-freeDictionaryAPI documentation master file, created by
    sphinx-quickstart on Sun May 16 17:56:36 2021.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to python-FreeDictionaryApi's documentation!
+Welcome to python-freeDictionaryAPI's documentation!
 ====================================================
 
 .. toctree::
-   :maxdepth: 5
+   :maxdepth: 2
    :caption: Contents:
 
    user_guide/index
@@ -18,5 +18,3 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/source/reference/clients/async_client.rst b/docs/source/reference/clients/async_client.rst
@@ -7,5 +7,5 @@ Requires `aiohttp <https://pypi.org/project/aiohttp/2.3.10/>`_ package to be ins
 
 .. autoclass:: freedictionaryapi.clients.async_client.AsyncDictionaryApiClient
     :members:
-    :show-inheritance:
     :inherited-members:
+    :show-inheritance:
diff --git a/docs/source/reference/clients/index.rst b/docs/source/reference/clients/index.rst
@@ -2,6 +2,7 @@ Clients
 =======
 
 .. toctree::
+    :maxdepth: 3
     :caption: Contents
 
     ~implemented_clients
diff --git a/docs/source/reference/clients/~base_clients.rst b/docs/source/reference/clients/~base_clients.rst
@@ -2,29 +2,28 @@ Base clients
 ============
 
 .. toctree::
+    :maxdepth: 2
     :caption: Contents
 
     base_sync_client
     base_async_client
 
 
-Here is 2 base API clients, abstract clients that
-might be inherited and overridden as you wish:
+Here is 2 base API clients. Abstract clients that
+might be inherited and overridden:
 
     1. **synchronous** :obj:`freedictionaryapi.clients.BaseDictionaryApiClient`
     2. **asynchronous** :obj:`freedictionaryapi.clients.BaseAsyncDictionaryApiClient`
 
-Here is list of the base clients.
 All you need to implement your own
 client it is to implement one method
-of the chosen base
-(no matter ``sync`` or ``async`` since both abstracts are prepared):
+of the chosen base:
 
-    - :obj:`freedictionaryapi.clients.BaseDictionaryApiClient.fetch_api_response`
-    - :obj:`freedictionaryapi.clients.BaseAsyncDictionaryApiClient.fetch_api_response`
+    - :meth:`freedictionaryapi.clients.BaseDictionaryApiClient.fetch_api_response`
+    - :meth:`freedictionaryapi.clients.BaseAsyncDictionaryApiClient.fetch_api_response`
 
 Method`s goals are very simple:
-    - fetch response that json-ized (something like ``response.json()``);
+    - fetch response that JSON-ized (something like ``response.json()``);
     - get response status code;
     - put it in right order in one tuple.
 
diff --git a/docs/source/reference/clients/~implemented_clients.rst b/docs/source/reference/clients/~implemented_clients.rst
@@ -2,6 +2,7 @@ Implemented clients
 ===================
 
 .. toctree::
+    :maxdepth: 2
     :caption: Contents
 
     sync_client
diff --git a/docs/source/reference/errors.rst b/docs/source/reference/errors.rst
@@ -22,7 +22,7 @@ Exceptions
     :show-inheritance:
 
 
-Exceptions` data
-^^^^^^^^^^^^^^^^
+Exceptions mapping
+^^^^^^^^^^^^^^^^^^
 
 .. autodata:: freedictionaryapi.errors.API_ERRORS_MAPPER
diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst
@@ -2,7 +2,7 @@ Reference
 =========
 
 .. toctree::
-   :maxdepth: 5
+   :maxdepth: 3
    :caption: Contents:
 
    clients/index
@@ -11,11 +11,3 @@ Reference
    urls
    languages
    errors
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/source/reference/parsers/index.rst b/docs/source/reference/parsers/index.rst
@@ -2,6 +2,7 @@ Parsers
 =======
 
 .. toctree::
+    :maxdepth: 3
     :caption: Contents
 
     ~implemented_parsers
diff --git a/docs/source/reference/parsers/~base_parsers.rst b/docs/source/reference/parsers/~base_parsers.rst
@@ -2,6 +2,7 @@ Base parsers
 ============
 
 .. toctree::
+    :maxdepth: 2
     :caption: Contents
 
     base_parser
diff --git a/docs/source/reference/parsers/~implemented_parsers.rst b/docs/source/reference/parsers/~implemented_parsers.rst
@@ -2,6 +2,7 @@ Implemented parsers
 ===================
 
 .. toctree::
+    :maxdepth: 2
     :caption: Contents
 
     response_parser
diff --git a/docs/source/reference/types/error.rst b/docs/source/reference/types/error.rst
@@ -1,7 +1,7 @@
 Error
 =====
 
-Despite of the so strong name it expresses **parsed object**.
+Despite of the so *strong* name it expresses **parsed object**.
 
 So this type is created for **API error responses parsing**.
 
diff --git a/docs/source/reference/types/~base_types.rst b/docs/source/reference/types/~base_types.rst
@@ -2,6 +2,7 @@ Base types
 ==========
 
 .. toctree::
+    :maxdepth: 2
     :caption: Contents
 
     base
diff --git a/docs/source/reference/types/~implemented_types.rst b/docs/source/reference/types/~implemented_types.rst
@@ -6,6 +6,7 @@ that has inner fields and some structure
 **is easily parsed**.
 
 .. toctree::
+    :maxdepth: 2
     :caption: Contents
 
     word
diff --git a/docs/source/user_guide/examples/index.rst b/docs/source/user_guide/examples/index.rst
@@ -2,6 +2,7 @@ Examples
 ========
 
 .. toctree::
+    :maxdepth: 2
     :caption: Contents
 
     sync_client_usage_example
@@ -11,3 +12,8 @@ Examples
 
     own_sync_client_example
     own_async_client_example
+
+
+.. note::
+
+    All examples have been written on 3.9 Python version.
diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst
@@ -2,6 +2,9 @@ User Guide
 ==========
 
 .. toctree::
+    :maxdepth: 2
     :caption: Contents
 
+    installation
+    quick_start
     examples/index
diff --git a/docs/source/user_guide/installation.rst b/docs/source/user_guide/installation.rst
@@ -0,0 +1,19 @@
+Installation Guide
+==================
+
+Using PIP
+^^^^^^^^^
+    .. code-block:: bash
+
+        $ pip install python-freeDictionaryAPI
+
+Using Pipenv
+^^^^^^^^^^^^
+    .. code-block:: bash
+
+        $ pipenv install python-freeDictionaryAPI
+
+
+.. note::
+
+    To import package use ``freedictionaryapi``.
diff --git a/docs/source/user_guide/quick_start.rst b/docs/source/user_guide/quick_start.rst
@@ -0,0 +1,130 @@
+Quick Start
+===========
+
+Let`s start:
+
+    .. note::
+
+    1. import client
+       (here I use synchronous client for simplicity; **httpx** is required)
+
+    .. code-block:: python
+
+        >>> from freedictionaryapi.clients.sync_client import DictionaryApiClient
+
+    2. init simple instance of client
+       (it is possible to set manually created **httpx** client on initialization)
+
+    .. code-block:: python
+
+        # it is possible to set
+        # default language for entire client
+        # by default: American English
+        >>> client = DictionaryApiClient()
+
+    3. fetch :obj:`freedictionaryapi.parsers.response_parser.DictionaryApiParser` parser
+
+    .. code-block:: python
+
+        # it is also possible to set
+        # language for request
+        # we`ll see this some later
+
+        # IMPORTANT:
+        # each method that makes API request
+        # have to be handled of API errors
+        # that are raised if API response is unsuccessful
+        >>> from freedictionaryapi.errors import DictionaryApiError
+
+        # so, handle errors...
+        >>> try:
+        ...     parser = client.fetch_parser('hello')
+        ... except DictionaryApiError:
+        ...     print('API error')
+
+    4. working with parser object and get all needed info
+       (see examples of parsing features in examples section)
+
+    .. code-block:: python
+
+        >>> parser.get_transcription()
+        '/həˈloʊ/'
+        >>> parser.get_link_on_audio_with_pronunciation()
+        'https://lex-audio.useremarkable.com/mp3/hello_us_1_rr.mp3'
+        >>> parser.get_all_definitions()
+        ['An utterance of “hello”; a greeting.', 'Say or shout “hello”; greet someone.', 'Used as a greeting or to begin a phone conversation.']
+        >>> parser.get_all_synonyms()
+        ['saluting', 'salutation', 'address', 'greeting', 'hello', 'hailing', 'welcome', 'hallo']
+        # here we get :obj:`freedictionaryapi.types.word.Word` object
+        >>> word = parser.word
+        # and now we can just navigate throw word object properties
+        >>> word.word
+        'hello'
+        >>> for phonetic in word.phonetics:
+        ...     print(phonetic)
+        Phonetic(text='/həˈloʊ/', audio='https://lex-audio.useremarkable.com/mp3/hello_us_1_rr.mp3')
+        Phonetic(text='/hɛˈloʊ/', audio='https://lex-audio.useremarkable.com/mp3/hello_us_2_rr.mp3')
+        >>> for meaning in word.meanings:
+        ...     print(meaning.part_of_speech)
+        ...     for definition in meaning.definitions:
+        ...             print(definition)
+        noun
+        Definition(definition='An utterance of “hello”; a greeting.', example='she was getting polite nods and hellos from people', synonyms=['greeting', 'welcome', 'salutation', 'saluting', 'hailing', 'address', 'hello', 'hallo'])
+
+        intransitive verb
+        Definition(definition='Say or shout “hello”; greet someone.', example='I pressed the phone button and helloed', synonyms=None)
+
+        exclamation
+        Definition(definition='Used as a greeting or to begin a phone conversation.', example='hello there, Katie!', synonyms=None)
+
+    5. or if you wish we can immediately get word object
+
+    .. code-block:: python
+
+        # here is also possible
+        # to set language for request
+        >>> try:
+        ...     word = client.fetch_word('small')
+        ... except DictionaryApiError:
+        ...     print('API error')
+        ... else:
+        ...     for phonetic in word.phonetics:
+        ...         print(phonetic)
+        Phonetic(text='/smɔl/', audio='https://lex-audio.useremarkable.com/mp3/small_us_6.mp3')
+
+    6. about other language usage
+
+    .. code-block:: python
+
+        # let`s learn Italian some :)
+        >>> from freedictionaryapi.languages import LanguageCodes
+        # supported languages:
+        >>> for language in LanguageCodes:
+        ...     print(language)
+        LanguageCodes.ARABIC
+        LanguageCodes.BRAZILIAN_PORTUGUESE
+        LanguageCodes.ENGLISH_UK
+        LanguageCodes.ENGLISH_US
+        LanguageCodes.FRENCH
+        LanguageCodes.GERMAN
+        LanguageCodes.HINDI
+        LanguageCodes.ITALIAN
+        LanguageCodes.JAPANESE
+        LanguageCodes.KOREAN
+        LanguageCodes.RUSSIAN
+        LanguageCodes.SPANISH
+        LanguageCodes.TURKISH
+        # and request with new language...
+        # do not forget to handle errors!
+        >>> parser = client.fetch_parser('ciao', LanguageCodes.ITALIAN)
+        >>> parser.get_transcription()
+        'cià·o'
+        >>> parser.get_all_definitions()
+        ['Voce confidenziale di saluto; anche come s.m. ( invar. ).']
+
+    7. do not forget to close client
+
+    .. code-block:: python
+
+        >>> client.close()
+
