install dir

docs/source/install/gen_documentation.rst

@@ -0,0 +1,102 @@
+.. _gen-documentation:
+
+Generate Documentation
+======================
+
+Before generating the Sphinx documentation, you should compile the package.
+
+Get the source code from the GitHub repository.
+
+.. prompt:: bash
+
+    git clone https://github.com/ameli/restoreio.git
+    cd restoreio
+
+Generate Sphinx Documentation
+-----------------------------
+
+Install `Pandoc <https://pandoc.org/>`_ by
+
+.. tab-set::
+
+   .. tab-item:: Ubuntu/Debian
+      :sync: ubuntu
+
+      .. prompt:: bash
+
+            sudo apt install pandoc -y
+
+   .. tab-item:: CentOS 7
+      :sync: centos
+
+      .. prompt:: bash
+
+          sudo yum install pandoc -y
+
+   .. tab-item:: RHEL 9
+      :sync: rhel
+
+      .. prompt:: bash
+
+          sudo dnf install pandoc -y
+
+   .. tab-item:: macOS
+      :sync: osx
+
+      .. prompt:: bash
+
+          sudo brew install pandoc -y
+
+   .. tab-item:: Windows (Powershell)
+      :sync: win
+
+      .. prompt:: powershell
+
+          scoop install pandoc
+
+Install the requirements for the Sphinx documentation by
+
+.. prompt:: bash
+
+    python -m pip install -r docs/requirements.txt
+
+The above command installs the required packages in Python's path directory. Make sure python's directory is on the `PATH`, for instance, by
+
+.. tab-set::
+
+    .. tab-item:: UNIX
+        :sync: unix
+
+        .. prompt:: bash
+
+            PYTHON_PATH=`python -c "import os, sys; print(os.path.dirname(sys.executable))"`
+            export PATH=${PYTHON_PATH}:$PATH
+
+    .. tab-item:: Windows (Powershell)
+        :sync: win
+
+        .. prompt:: powershell
+
+            $PYTHON_PATH = (python -c "import os, sys; print(os.path.dirname(sys.executable))")
+            $env:Path += ";$PYTHON_PATH"
+
+Now, build the documentation:
+
+.. tab-set::
+
+    .. tab-item:: UNIX
+        :sync: unix
+
+        .. prompt:: bash
+
+            make clean html --directory=docs
+
+    .. tab-item:: Windows (Powershell)
+        :sync: win
+
+        .. prompt:: powershell
+
+            cd docs
+            make.bat clean html
+
+The main page of the documentation can be found in ``/docs/build/html/index.html``. 

docs/source/install/install.rst

@@ -0,0 +1,39 @@
+.. _install:
+
+Install
+*******
+
+For the majority of users, this package can be easily installed from Python wheels using either `pip <https://pip.pypa.io/en/stable/>`__ or `conda <https://docs.conda.io/en/latest/>`__. More information on installation can be found in the :ref:`Install from Wheels <install-wheels>` or :ref:`Install in Virtual Environment <virtual-env>` sections.
+
+If you encounter any issues during the installation process, please consult the :ref:`Troubleshooting <troubleshooting>` section for potential solutions to common installation problems.
+
+To generate this documentation, you may refer to :ref:`Generate Documentation <gen-documentation>` sections. Instructions for testing the package are available in the :ref:`Test Package <test-package>` section.
+
+.. toctree::
+    :hidden:
+
+    self
+
+.. toctree::
+    :maxdepth: 2
+    :numbered:
+
+    Install from Wheels <install_wheels>
+    Install in Virtual Environment <virtual_env>
+    Troubleshooting <troubleshooting>
+    Generate Documentation <gen_documentation>
+    Test Package <test_package>
+
+.. |implementation| image:: https://img.shields.io/pypi/implementation/restoreio
+.. |pyversions| image:: https://img.shields.io/pypi/pyversions/restoreio
+.. |format| image:: https://img.shields.io/pypi/format/restoreio
+.. |conda| image:: https://anaconda.org/s-ameli/restoreio/badges/installer/conda.svg
+   :target: https://anaconda.org/s-ameli/restoreio
+.. |platforms| image:: https://img.shields.io/conda/pn/s-ameli/restoreio?color=orange?label=platforms
+   :target: https://anaconda.org/s-ameli/restoreio
+.. |release| image:: https://img.shields.io/github/v/tag/ameli/restoreio
+   :target: https://github.com/ameli/restoreio/releases/
+.. |conda-platform| image:: https://anaconda.org/s-ameli/restoreio/badges/platforms.svg
+   :target: https://anaconda.org/s-ameli/restoreio
+.. |repo-size| image:: https://img.shields.io/github/repo-size/ameli/restoreio
+   :target: https://github.com/ameli/restoreio

docs/source/install/install_wheels.rst

@@ -0,0 +1,54 @@
+.. _install-wheels:
+
+Install from Wheels
+===================
+
+|project| offers Python wheels for a variety of operating systems and Python versions. These wheels are available on both `PyPI <https://pypi.org/project/restoreio>`_ and `Anaconda Cloud <https://anaconda.org/s-ameli/restoreio>`_, providing a convenient way to install the package using either ``pip`` or ``conda``.
+
+Install with ``pip``
+--------------------
+
+|pypi|
+
+First, ensure that you have ``pip`` installed
+
+.. prompt:: bash
+
+    python -m ensurepip --upgrade
+
+For further detail on installing ``pip``, refer to `pip installation documentation <https://pip.pypa.io/en/stable/installation/>`__.
+
+To install |project| and its Python dependencies using ``pip`` by
+
+.. prompt:: bash
+
+    python -m pip install --upgrade pip
+    python -m pip install restoreio
+
+If you are using `PyPy <https://www.pypy.org/>`__ instead of Python, you can first ensure ``pip`` is installed by
+
+.. prompt:: bash
+
+    pypy -m ensurepip --upgrade
+
+Next, you can install |project| as follows:
+
+.. prompt:: bash
+
+    pypy -m pip install --upgrade pip
+    pypy -m pip install restoreio
+
+Install with ``conda``
+----------------------
+
+|conda-version|
+
+Alternatively, you can install |project| via ``conda``. To do so, you may refer to the `conda instalation documentation <https://conda.io/projects/conda/en/latest/user-guide/install/index.html>`__ to set up ``conda`` on your system. Once ``conda`` is ready, you can install |project| along with its Python dependencies by using the following command
+
+.. prompt:: bash
+
+    conda install -c s-ameli -c conda-forge restoreio -y
+
+.. |pypi| image:: https://img.shields.io/pypi/v/restoreio
+.. |conda-version| image:: https://img.shields.io/conda/v/s-ameli/restoreio
+   :target: https://anaconda.org/s-ameli/restoreio

docs/source/install/test_package.rst

@@ -0,0 +1,60 @@
+.. _test-package:
+
+Test Package
+************
+
+You can test the package using either `pytest <https://docs.pytest.org/>`__ or `tox <https://tox.wiki/en/4.7.0/>`__.
+
+Test with ``pytest``
+====================
+
+|codecov-devel|
+
+The package can be tested by running several `test scripts <https://github.com/ameli/restoreio/tree/main/tests>`_, which test all `sub-packages <https://github.com/ameli/restoreio/tree/main/restoreio>`_ and `examples <https://github.com/ameli/restoreio/tree/main/examples>`_.
+
+Clone the source code from the repository and install the required test packages by
+
+.. prompt:: bash
+
+    git clone https://github.com/ameli/restoreio.git
+    cd restoreio
+    python -m pip install -r tests/requirements.txt
+    python setup.py install
+
+To automatically run all tests, use ``pytest`` which is installed by the above commands.
+
+.. prompt:: bash
+
+    mv restoreio restoreio-do-not-import
+    pytest
+
+.. attention::
+
+    To properly run ``pytest``, rename ``/restoreio/restoreio`` directory as shown in the above code. This makes ``pytest`` to properly import |project| from the installed location, not from the source code directory.
+
+Test with ``tox``
+=================
+
+To run a test in a virtual environment, use ``tox`` as follows:
+
+1. Clone the source code from the repository:
+
+   .. prompt:: bash
+
+       git clone https://github.com/ameli/restoreio.git
+
+2. Install `tox <https://tox.wiki/en/latest/>`_:
+
+   .. prompt:: bash
+
+       python -m pip install tox
+
+3. Run tests by
+
+   .. prompt:: bash
+
+       cd restoreio
+       tox
+
+.. |codecov-devel| image:: https://img.shields.io/codecov/c/github/ameli/restoreio
+   :target: https://codecov.io/gh/ameli/restoreio

docs/source/install/troubleshooting.rst

@@ -0,0 +1,60 @@
+.. _troubleshooting:
+
+Troubleshooting
+===============
+
+Issue with ``basemap``
+----------------------
+
+When using this package, You may encountered this error:
+
+.. prompt::
+
+    ModuleNotFoundError: No module named 'mpl_toolkits.basemap'
+
+or the following error:
+
+.. prompt::
+
+    FileNotFoundError: [Errno 2] No such file or directory: '/opt/miniconda3/lib/python3.10/site-packages/basemap_data_hires-1.3.2-py3.10.egg/mpl_toolkits/basemap_data/epsg'
+
+To solve these issues, first, install ``libgeos`` library by
+
+.. prompt::
+
+    sudo apt install libgeos3.10.2 libgeos-dev -y
+
+
+Next, install ``basemap`` package directly thought its `GitHub repository <https://github.com/matplotlib/basemap>`__ as follows. 
+
+.. prompt::
+
+    python -m pip install git+https://github.com/matplotlib/basemap#subdirectory=packages/basemap
+    python -m pip install git+https://github.com/matplotlib/basemap#subdirectory=packages/basemap_data
+    python -m pip install git+https://github.com/matplotlib/basemap#subdirectory=packages/basemap_data_hires
+
+If the issue is not yet resolved with the above solutions, try reinstalling all prerequisite packages using ``conda`` instead of ``pip`` as follows:
+
+.. prompt::
+
+    conda install -c conda-forge --file conda-recipe/requirements_conda.txt
+
+In the above command, the file ``requirements_conda.txt`` is located in the `source code <https://github.com/ameli/restoreio>`__ under ``/conda-receipe`` directory.
+
+Issue with ``geos``
+-------------------
+
+When building the sphinx documentation, you may get this error:
+
+.. prompt::
+
+    Extension error (pydata_sphinx_theme):
+    Handler <function _overwrite_pygments_css at 0x7fb8efce2cb0> for event 'build-finished' threw an exception (exception: [Errno 13] Permission denied: '/opt/miniconda3/lib/python3.10/site-packages/geos-0.2.3-py3.10.egg/EGG-INFO/entry_points.txt')
+    make: *** [Makefile:20: html] Error 2
+
+To resolve this issue, uninstall, then install the ``geos`` package:
+
+.. prompt::
+
+    python -m pip uninstall geos
+    python -m pip install --upgrade geos