Merge pull request #53 from MEHRSHAD-MIRSHEKARY/docs/add-rst-docs

📚 Add Sphinx Documentation Setup and Initial RST Files

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'django_logging'
+copyright = '2024, django_logging'
+author = 'ARYAN NIKNEZHAD, MEHRSHAD-MIRSHEKARY'
+
+# The full version, including alpha/beta/rc tags
+release = '1.0.0'
+
+master_doc = 'index'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',   # Auto-generate API documentation
+    'sphinx.ext.napoleon',  # Support for NumPy and Google style docstrings
+    'sphinx.ext.viewcode',  # Add links to highlighted source code
+    'sphinx.ext.githubpages'  # Publish documentation on GitHub Pages
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom static files
+html_logo = '_static/logo.png'
+html_favicon = '_static/favicon.ico'

docs/contributing.rst

@@ -0,0 +1,159 @@
+Contributing to django_logging
+==============================
+
+We’re excited that you’re interested in contributing to `django_logging`! Whether you’re fixing a bug, adding a feature, or improving the project, your help is appreciated.
+
+Overview
+--------
+
+- **Setting Up Your Environment**
+- **Testing Your Changes**
+- **Code Style Guidelines**
+- **Utilizing Pre-commit Hooks**
+- **Creating a Pull Request**
+- **Reporting Issues**
+- **Resources**
+
+Setting Up Your Environment
+---------------------------
+
+1. **Fork the Repository:**
+
+   Begin by forking the `django_logging` repository on GitHub. This creates your own copy where you can make changes.
+
+2. **Clone Your Fork:**
+
+   Use the following command to clone your fork locally:
+
+   .. code-block:: bash
+
+       git clone https://github.com/your-username/django_logging.git
+       cd django_logging
+
+3. **Install Dependencies:**
+
+   Install the necessary dependencies using `Poetry`. If Poetry isn't installed on your machine, you can find installation instructions on the `Poetry website <https://python-poetry.org/docs/#installation>`_.
+
+   .. code-block:: bash
+
+       poetry install
+
+4. **Create a Feature Branch:**
+
+   It’s a good practice to create a new branch for your work:
+
+   .. code-block:: bash
+
+       git checkout -b feature/your-feature-name
+
+Testing Your Changes
+--------------------
+
+We use `pytest` for running tests. Before submitting your changes, ensure that all tests pass:
+
+.. code-block:: bash
+
+    poetry run pytest
+
+If you’re adding a new feature or fixing a bug, don’t forget to write tests to cover your changes.
+
+Code Style Guidelines
+----------------------
+
+Maintaining a consistent code style is crucial. We use `black` for code formatting and `isort` for import sorting. Make sure your code adheres to these styles:
+
+.. code-block:: bash
+
+    poetry run black .
+    poetry run isort .
+
+For linting, `pylint` is used to enforce style and catch potential errors:
+
+.. code-block:: bash
+
+    poetry run pylint django_logging
+
+Utilizing Pre-commit Hooks
+--------------------------
+
+Pre-commit hooks are used to automatically check and format code before you make a commit. This ensures consistency and quality in the codebase.
+
+1. **Install Pre-commit:**
+
+   .. code-block:: bash
+
+       poetry add --dev pre-commit
+
+2. **Set Up the Hooks:**
+
+   Install the pre-commit hooks by running:
+
+   .. code-block:: bash
+
+       poetry run pre-commit install
+
+3. **Manual Hook Execution (Optional):**
+
+   To run all hooks manually on your codebase:
+
+   .. code-block:: bash
+
+       poetry run pre-commit run --all-files
+
+Creating a Pull Request
+-----------------------
+
+Once your changes are ready, follow these steps to submit them:
+
+1. **Commit Your Changes:**
+
+   Write clear and concise commit messages. Following the `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_ format is recommended:
+
+   .. code-block:: bash
+
+       git commit -am 'feat: add custom logging formatter'
+
+2. **Push Your Branch:**
+
+   Push your branch to your fork on GitHub:
+
+   .. code-block:: bash
+
+       git push origin feature/your-feature-name
+
+3. **Open a Pull Request:**
+
+   Go to the original `django_logging` repository and open a pull request. Include a detailed description of your changes and link any related issues.
+
+4. **Respond to Feedback:**
+
+   After submitting, a maintainer will review your pull request. Be prepared to make revisions based on their feedback.
+
+Reporting Issues
+----------------
+
+Found a bug or have a feature request? We’d love to hear from you!
+
+1. **Open an Issue:**
+
+   Head over to the `Issues` section of the `django_logging` repository and click "New Issue".
+
+2. **Describe the Problem:**
+
+   Fill out the issue template with as much detail as possible. This helps us understand and address the issue more effectively.
+
+Resources
+---------
+
+Here are some additional resources that might be helpful:
+
+- `Poetry Documentation <https://python-poetry.org/docs/>`_
+- `Black Documentation <https://black.readthedocs.io/en/stable/>`_
+- `isort Documentation <https://pycqa.github.io/isort/>`_
+- `pytest Documentation <https://docs.pytest.org/en/stable/>`_
+- `pylint Documentation <https://pylint.pycqa.org/en/latest/>`_
+- `Pre-commit Documentation <https://pre-commit.com/>`_
+
+---
+
+Thank you for your interest in contributing to `django_logging`! We look forward to your contributions.

docs/index.rst

@@ -0,0 +1,67 @@
+Welcome to django_logging Documentation!
+========================================
+
+.. |br| raw:: html
+
+   <br />
+
+.. image:: https://img.shields.io/pypi/v/django_logging
+   :target: https://pypi.org/project/django_logging/
+   :alt: PyPI release
+
+.. image:: https://img.shields.io/pypi/pyversions/django_logging
+   :target: https://pypi.org/project/django_logging/
+   :alt: Supported Python versions
+
+.. image:: https://img.shields.io/pypi/djversions/django_logging
+   :target: https://pypi.org/project/django_logging/
+   :alt: Supported Django versions
+
+.. image:: https://img.shields.io/readthedocs/django_logging
+   :target: https://django_logging.readthedocs.io/
+   :alt: Documentation
+
+|br|
+
+`django_logging` is a Django package designed to extend and enhance Python’s built-in logging capabilities. By providing customizable configurations and advanced features, it offers developers a comprehensive logging solution tailored specifically for Django applications.
+
+Supported Versions
+------------------
+
+`django_logging` supports the following combinations of Django and Python versions:
+
+==========  =======================
+  Django      Python
+==========  =======================
+4.2         3.8, 3.9, 3.10, 3.11, 3.12
+5.0         3.10, 3.11, 3.12
+5.1         3.10, 3.11, 3.12
+==========  =======================
+
+Documentation
+-------------
+
+The documentation is organized into the following sections:
+
+.. toctree::
+   :maxdepth: 2
+
+   quick_start
+   usage
+   settings
+   contributing
+   rules
+
+Issues
+------
+If you have questions or have trouble using the app please file a bug report at:
+
+https://github.com/ARYAN-NIKNEZHAD/django_logging
+
+
+Indices and tables
+==================
+
+* :ref:`search`
+* :ref:`genindex`
+* :ref:`modindex`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/quick_start.rst

@@ -0,0 +1,51 @@
+Quick Start
+===========
+
+Getting Started with `django_logging` is simple. Follow these steps to get up and running quickly:
+
+1. **Installation**
+
+   Install `django_logging` via pip:
+
+   .. code-block:: shell
+
+      $ pip install django_logging
+
+2. **Add to Installed Apps**
+
+   Add `django_logging` to your `INSTALLED_APPS` in your Django settings file:
+
+   .. code-block:: python
+
+      INSTALLED_APPS = [
+          ...
+          'django_logging',
+          ...
+      ]
+
+3. **Default Configuration**
+
+   By default, `django_logging` is configured to use its built-in settings. You do not need to configure anything manually unless you want to customize the behavior. The default settings will automatically handle logging with predefined formats and options.
+
+4. **Verify Installation**
+
+   To ensure everything is set up correctly, run your Django development server:
+
+    .. code-block:: shell
+
+      python manage.py runserver
+
+   By default, `django_logging` will log an initialization message to the console that looks like this:
+
+    .. code-block:: text
+
+      INFO | django_logging | Logging initialized with the following configurations:
+      Log File levels: ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'].
+      Log files are being written to: logs.
+      Console output level: DEBUG.
+      Colorize console: True.
+      Log date format: %Y-%m-%d %H:%M:%S.
+      Email notifier enabled: False.
+
+
+That's it! `django_logging` is ready to use with default settings. For further customization, refer to the [Settings](settings.rst) section.