Improve package documentation (#53)

* Update docstring and other modules documentations.

* Documentation improved

docs/api.rst

@@ -1,41 +1,49 @@
-===================
-⚙API documentation
-===================
+=================
+API documentation
+=================
 
-main
-----
+Entry application
+-----------------
+
+The entry point for the package ``sphinx-versioned-docs`` is through :func:`sphinx_versioned.__main__.main`.
+The function is actually a Typer CLI with the various command-line options available.
 
 .. automodule:: sphinx_versioned.__main__
     :members:
-    :undoc-members:
+    :private-members:
     :show-inheritance:
 
-----------
 
-sphinx extension
+Building workflow
+-----------------
+
+.. automodule:: sphinx_versioned.build
+    :members:
+    :private-members:
+    :show-inheritance:
+
+Sphinx extension
 ----------------
 
+The sphinx-extension is added by default on running ``sphinx-versioned`` to inject the versions flyout
+menu directly to the html files.
+
 .. automodule:: sphinx_versioned.sphinx_
     :members:
-    :undoc-members:
+    :private-members:
     :show-inheritance:
 
-----------
+-------------------------------------------
 
-versions container
-------------------
+Utiliies/ Libraries
+-------------------
 
 .. automodule:: sphinx_versioned.versions
     :members:
-    :undoc-members:
+    :private-members:
     :show-inheritance:
 
-----------
-
-util
-----
-
 .. automodule:: sphinx_versioned.lib
     :members:
-    :undoc-members:
+    :private-members:
     :show-inheritance:

docs/changes/53.doc.rst

@@ -0,0 +1 @@
+Improved package-wide documentation. Added doc-strings and improved tutorial and installation instructions for fresh users.

docs/conf.py

@@ -247,11 +247,10 @@
 # texinfo_no_detailmenu = False
 
 # Example configuration for intersphinx: refer to the Python standard library.
-# intersphinx_mapping = {
-#     "python": ("http://docs.python.org/", None),
-#     "pytest": ("https://docs.pytest.org/en/stable/", None),
-#     "urllib3": ("https://urllib3.readthedocs.io/en/stable/", None),
-#     "requests": ("https://docs.python-requests.org/en/master/", None),
-#     "aiohttp": ("https://docs.aiohttp.org/en/stable/", None),
-#     "sqlite3": ("https://docs.python.org/3/library/sqlite3.html", None),
-# }
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "pytest": ("https://docs.pytest.org/en/stable/", None),
+    "aiohttp": ("https://docs.aiohttp.org/en/stable/", None),
+    "sphinx": ("https://www.sphinx-doc.org/", None),
+    "gitpython": ("https://gitpython.readthedocs.io/en/stable/", None),
+}

docs/contributing.rst

@@ -9,35 +9,29 @@ Welcome contributors!
 Installation
 ============
 
-In order to contribute to this project you'll need to install the package via source with all dependencies.
+In order to contribute to this project you'll need to install the package via source with all dependencies. Follow :ref:`dev build <dev-version>` for more info.
 
-.. code:: bash
+.. code:: console
 
-   python -m pip install -e .[all]
+   $ python -m pip install -e .[all]
 
 Build and upload a new version of sphinx-versioned-docs
 =======================================================
 
-Update the README.rst
----------------------
-
-You need to add a section in the ``README.rst`` for the newly created version (follow the pattern of other versions).
-
-
 Generate package to distribute
 ------------------------------
 
 This builds your python project and creates the `dist` directory (among other things).
 
-.. code:: bash
+.. code:: console
 
-   python3 setup.py sdist bdist_wheel
+   $ python3 setup.py sdist bdist_wheel
 
 Upload your package to nexus
 ----------------------------
 
-.. code:: bash
+.. code:: console
 
-   twine upload dist/*
+   $ twine upload dist/*
 
-After this command, your package is available on  https://pypi.org. Anyone can install it using `pip install sphinx-versioned-docs`.
+After this command, your package is available on  https://pypi.org. Anyone can install it using ``pip install sphinx-versioned-docs``.

docs/index.rst

@@ -5,19 +5,21 @@ sphinx-versioned-docs
 A Sphinx extension that lets you build Sphinx docs for all versions of your project without needing special hosting
 services.
 
-.. include:: ../README.rst
-
 Project Links
 =============
 
+* Documentation: https://sphinx-versioned-docs.readthedocs.io/en/latest/
 * Source code: https://github.com/devanshshukla99/sphinx-versioned-docs
+* PyPI homepage: https://pypi.org/project/sphinx-versioned-docs/
+* conda-forge: https://anaconda.org/conda-forge/sphinx-versioned-docs
 
 .. toctree::
     :maxdepth: 2
     :caption: General
 
     install
     tutorial
+    settings
     themes
     api
 

docs/install.rst

@@ -4,31 +4,84 @@
 Installation
 ============
 
+The ``sphinx-versioned-docs`` project has the following requirements.
+
 .. _requirements-to-use:
 
 Requirements
 ============
 
-- GitPython>=3.1.31
-- loguru>=0.7.0
-- setuptools>=66.0.0
-- sphinx>=4.6.0
-- typer>=0.9.0
-- rich
+.. code-block:: markdown
+
+    GitPython>=3.1.31
+    loguru>=0.7.0
+    setuptools>=66.0.0
+    sphinx>=4.6.0
+    typer>=0.9.0
+    rich
+
+Installing
+==========
+
+Now, it can be installed via the following methods:
+
+Installing using pip
+--------------------
+
+For this you will require that python3 and `pip <https://pip.pypa.io/en/stable/installation/>`__ are already installed.
+
+.. code-block:: console
+
+    $ pip install sphinx-versioned-docs
+
+Installing using conda
+----------------------
+
+In this method, please make sure that anaconda/conda is properly installed:
+
+.. code-block:: console
+
+    $ conda install sphinx-versioned-docs
+
+In order to create a separate environment in conda, follow these instructions:
+
+.. code-block:: console
+
+    $ conda create --name versioned
+    $ conda activate versioned
+    $ conda install sphinx-versioned-docs
 
 Installing from source
 ----------------------
 
+This method typically installs that lastest developer version of the package, however, it be used to install stable branches too.
+
+To install the latest developer version:
+
 .. code-block:: console
 
     $ git clone https://github.com/devanshshukla99/sphinx-versioned-docs
     $ cd sphinx-versioned-docs
     $ pip install .
 
+To install the latest stable release, specified via the ``<release tag>``:
 
-Installing using pip
---------------------
+.. code-block:: console
+
+    $ git clone https://github.com/devanshshukla99/sphinx-versioned-docs
+    $ cd sphinx-versioned-docs
+    $ git checkout <release tag>
+    $ pip install .
+
+.. _dev-version:
+
+Installing the developer version
+--------------------------------
 
-.. code-block:: bash
+If you are interested in contributing to the project, then you can setup the developer environment by using:
 
-    pip install sphinx-versioned-docs
+.. code-block:: console
+
+    $ git clone https://github.com/devanshshukla99/sphinx-versioned-docs
+    $ cd sphinx-versioned-docs
+    $ pip install -e .[all]

docs/settings.rst

@@ -0,0 +1,85 @@
+.. _settings:
+
+========
+Settings
+========
+
+.. code-block::
+
+    sphinx-versioned [OPTIONS]
+
+The ``sphinx-versioned-docs`` reads options from two sources:
+
+    * From the sphinx ``conf.py`` file.
+    * From the provided command-line-arguments.
+
+Configuration File Arguments
+============================
+
+Currently, only the ``sv_project_url`` can be set via the ``conf.py``. More options coming in future releases.
+
+.. option:: sv_project_url: <url>
+
+    Setting this variable will make sure that the ``Project home`` is listed on the versions selector badge/menu.
+
+Command Line Arguments
+======================
+
+These command line options must be specified when executing the ``sphinx-versioned`` command.
+
+.. option:: -c <directory>, --chdir <directory>
+
+    Change the current working directory.
+
+.. option:: --git-root <directory>
+
+    Path to the git-root of the current repo. Default is the current working directory.
+
+.. option:: -o <directory>, --output <directory>
+
+    Set the output directory.
+
+.. option:: --local-conf <directory>
+
+    Path to the ``conf.py`` for ``sphinx-versioned``. Default is ``conf.py`` at the current working directory.
+
+.. option:: --reset-intersphinx
+
+    Resets intersphinx mapping; acts as a patch for issue `#17 <https://github.com/devanshshukla99/sphinx-versioned-docs/issues/17>`__. Default is `False`.
+
+.. option:: --sphinx-compability
+
+    Adds compatibility for older sphinx versions by monkey patching certain functions. Default is `False`.
+
+.. option:: --prebuild, --no-prebuild
+
+    Pre-build all versions to make sure ``sphinx-build`` has no issues and pass-on the successful builds to ``sphinx-versioned-docs``. Default is `True`.
+
+.. option:: -b <branch names separated by `,` or `|`>, --branches <branch names separated by `,` or `|`>
+
+    Build docs and the version selector menu only for certain tags and branches.
+
+.. option:: -m <branch name>, --main-branch <branch name>
+
+    Specify the main-branch to which the top-level ``index.html`` redirects to. Default is ``main``.
+
+.. option:: --quite, --no-quite
+
+    Silents the output from `sphinx`. Use `--no-quite` to get complete-output from `sphinx`. Default is `True`.
+
+.. option:: -v, --verbose
+
+    Passed directly to sphinx. Specify more than once for more logging in sphinx. Default is `False`.
+
+.. option:: -log <level>, --log <level>
+
+    Provide logging level. Example `--log` debug, Default is ``info``.
+    Logging levels can be ``trace``, ``debug``, ``warn``, ``info``, etc.
+
+.. option:: --force
+
+    Force branch selection. Use this option to build detached head/commits. Default is `False`.
+
+.. option:: --help
+
+    Show the help message in command-line.

docs/themes.rst

@@ -6,7 +6,7 @@ Supported themes
 
 This project supports multiple themes such as:
 
-|CI themes|
+|Build|
 
 - sphinx_rtd_theme
 - astropy_sphinx_theme
@@ -16,5 +16,5 @@ This project supports multiple themes such as:
 - bizstyle
 - traditional
 
-.. |CI themes| image:: https://github.com/devanshshukla99/sphinx-versioned-docs/actions/workflows/CI-themes.yml/badge.svg
-    :alt: CI themes
+.. |Build| image:: https://github.com/devanshshukla99/sphinx-versioned-docs/actions/workflows/main.yml/badge.svg
+    :alt: CI