this should fix all tech and usage docs

Author: csparpa

sphinx/index.rst

@@ -28,7 +28,7 @@ What APIs can I access with PyOWM?
 
 With PyOWM you can interact programmatically with the following OpenWeatherMap web APIs:
 
- - **Weather API v2.5**, offering
+ - **Weather API v2.5** + **OneCall API**, offering
     + current weather data
     + weather forecasts
     + weather history
@@ -38,190 +38,219 @@ With PyOWM you can interact programmatically with the following OpenWeatherMap w
  - **Stations API v3.0**, allowing to create and manage meteostation and publish local weather measurements
  - **Weather Alerts API v3.0**, allowing to set triggers on weather conditions and areas and poll for spawned alerts
 
-And You can also get **image tiles** for several map layers provided by OWM
+And you can also get **image tiles** for several map layers provided by OWM
 
 
 The documentation of OWM APIs can be found on the OWM Website_
 
 .. _Website: https://openweathermap.org/api
 
 
-Important note
---------------
+Used to work with PyOWM v2?
+---------------------------
 
 PyOWM v3 is a brand new branch of the library and therefore differs from PyOWM v2 branch.
 This means that **v3 offers no retrocompatibility with v2: this might result in your code breaking** if
 it uses PyOWM v2 and you uncarefully update!
+Moreover, PyOWM v3 runs on Python 3 only.
 
-Moreover, PyOWM v3 only runs on Python 2 while PyOWM v2 supports both Python 2 and 3 (until January, 1st 2020)
+PyOWM v2 will follow this Timeline_
 
-Please take a look here, you can get full detail and migration guidelines
+It is highly recommended that you upgrade your PyOWM v2 dependency to PyOWM v3: follow this guide for Migrating_
 
-Maintenance Streams Timeline
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. toctree::
-   :maxdepth: 1
 
-   v3/maintenance-streams-timelines
-   v3/migration-guide-pyowm-v2-to-v3
+.. _Timeline: v3/maintenance-streams-timelines.html
+.. _Migrating: v3/migration-guide-pyowm-v2-to-v3.html
 
 
 Supported environments and Python versions
 ------------------------------------------
 
 PyOWM runs on Windows, Linux and MacOS.
-
 PyOWM runs on Python 3.7+
 
 
-Installation
-------------
-
-pip
-~~~
-
-The easiest method of all:
-
-.. code::
-
-    $ pip install pyowm
-
-If you already have PyOWM 2.x installed and want to upgrade to safely update it to the latest 2.x release just run:
-
-.. code::
-
-    $ pip install --upgrade pyowm>=2.0,<3.0
-
-
-Get the lastest development version
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can install the development trunk with _pip_:
-
-.. code::
-
-    $ pip install git+https://github.com/csparpa/pyowm.git@develop
-
+Usage and Technical Documentation
+---------------------------------
 
-but be aware that it might not be stable!
-
-setuptools
-~~~~~~~~~~
+PyOWM v3 documentation
+~~~~~~~~~~~~~~~~~~~~~~
 
-You can install from source using _setuptools_: either download a release from GitHub or just take the latest main branch), then:
-
-.. code::
-
-   $ unzip <zip archive>   # or tar -xzf <tar.gz archive>
-   $ cd pyowm-x.y.z
-   $ python setup.py install
-
-The .egg will be installed into the system-dependent Python libraries folder
-
-
-Distribution packages
-~~~~~~~~~~~~~~~~~~~~~
+Quick code recipes (work in progress)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. toctree::
+   :maxdepth: 1
 
-On Windows you have EXE installers
+   v3/code-recipes
 
-On ArchLinux you can use the Yaourt package manager, run:
+PyOWM v3 software API documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This is the Python API documentation of PyOWM:
 
-.. code::
+.. toctree::
+   :maxdepth: 1
 
-   Yaourt -S python2-owm  # Python 2.7 (https://aur.archlinux.org/packages/python-owm)
-   Yaourt -S python-owm   # Python 3.x (https://aur.archlinux.org/packages/python2-owm)
+   pyowm
 
-On OpenSuse you can use with YaST/Zypper package manager, run:
+Description of PyOWM configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. toctree::
+   :maxdepth: 1
 
-.. code::
+   v3/pyowm-configuration-description
 
-   zypper install python-pyowm
 
-Quick code recipes
-------------------
+Global PyOWM instantiation documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
 
-   v3/code-recipes
+   v3/global-pyowm-usage-examples
 
 
-Legacy PyOWM v2 usage documentation
------------------------------------
+City ID registry documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. toctree::
+   :maxdepth: 1
 
-Here are some usage examples for the different OWM APIs: these examples and guides refer to PyOWM library
-versions belonging to the old 2.x stream
+   v3/city-id-registry-examples
 
 
 Weather API examples
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
 
-   usage-examples-v2/weather-api-usage-examples
-   usage-examples-v2/weather-api-object-model
+   v3/weather-api-usage-examples
 
 Agro API examples
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 .. toctree::
    :maxdepth: 1
 
-   usage-examples-v2/agro-api-usage-examples
+   v3/agro-api-usage-examples
 
 
 UV API examples
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
 
-   usage-examples-v2/uv-api-usage-examples
+   v3/uv-api-usage-examples
 
 
 Air Pollution API examples
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. toctree::
    :maxdepth: 1
 
-   usage-examples-v2/air-pollution-api-usage-examples
+   v3/air-pollution-api-usage-examples
 
 Stations API examples
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
 
-   usage-examples-v2/stations-api-usage-examples
+   v3/stations-api-usage-examples
 
 Alerts API examples
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
 
-   usage-examples-v2/alerts-api-usage-examples
+   v3/alerts-api-usage-examples
 
 Map tiles client examples
-~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^
 .. toctree::
    :maxdepth: 1
 
-   usage-examples-v2/map-tiles-client-examples.md
+   v3/map-tiles-client-usage-examples.md
 
+PyOWM Exceptions
+^^^^^^^^^^^^^^^^
+.. toctree::
+   :maxdepth: 1
 
-PyOWM v3 usage documentation
-----------------------------
-Coming soon!
+   v3/exceptions.md
 
+Utility functions examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. toctree::
+   :maxdepth: 1
 
-PyOWM software API documentation
---------------------------------
+   v3/utilities-usage-examples.md
 
-This is the Python API documentation of PyOWM:
 
-.. toctree::
-   :maxdepth: 1
+Legacy PyOWM v2 documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Please refer to historical archives on Readthedocs or the GitHub repo for this
+
+
+Installation
+------------
+
+pip
+~~~
+
+The easiest method of all:
+
+.. code::
+
+    $ pip install pyowm
+
+If you already have PyOWM 2.x installed and want to upgrade to safely update it to the latest 2.x release just run:
+
+.. code::
+
+    $ pip install --upgrade pyowm>=2.0,<3.0
+
+
+Get the lastest development version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can install the development trunk with _pip_:
+
+.. code::
+
+    $ pip install git+https://github.com/csparpa/pyowm.git@develop
+
+
+but be aware that it might not be stable!
+
+setuptools
+~~~~~~~~~~
+
+You can install from source using _setuptools_: either download a release from GitHub or just take the latest main branch), then:
+
+.. code::
+
+   $ unzip <zip archive>   # or tar -xzf <tar.gz archive>
+   $ cd pyowm-x.y.z
+   $ python setup.py install
+
+The .egg will be installed into the system-dependent Python libraries folder
 
-   pyowm
 
+Distribution packages
+~~~~~~~~~~~~~~~~~~~~~
+
+On Windows you have EXE installers
+
+On ArchLinux you can use the Yaourt package manager, run:
+
+.. code::
+
+   Yaourt -S python2-owm  # Python 2.7 (https://aur.archlinux.org/packages/python-owm)
+   Yaourt -S python-owm   # Python 3.x (https://aur.archlinux.org/packages/python2-owm)
+
+On OpenSuse you can use with YaST/Zypper package manager, run:
+
+.. code::
+
+   zypper install python-pyowm
 
 
 How to contribute