readthedocs (#229)

* Switch README file from markdown to reStructuredText format

In this commit, the README.md file has been deleted and replaced by a README.rst file. This change enables a better integration with various Python document processing tools and is more universally accepted in Python projects.

* Refactor README layout and description

The display of various badges was reorganized for better readability. The description of the 'GitHub commits since latest release' badge was also simplified for a more concise description.

* Fix formatting issue in README.rst

An extra line break, which was previously causing a formatting issue in the README.rst file, has been removed. The document structure and format are now consistent.

* Add Sphinx documentation setup

This commit introduces a configuration for the Sphinx documentation builder with the `conf.py` setup file. It adds an `index.rst` file for documentation content and automation files (`make.bat` and `Makefile`) to build the documentation.

* style: format code with Black, isort and Ruff Formatter

This commit fixes the style issues introduced in 569e5d4 according to the output
from Black, isort and Ruff Formatter.

Details: #229

* Add Sphinx documentation setup

This commit introduces a configuration for the Sphinx documentation builder with the `conf.py` setup file. It adds an `index.rst` file for documentation content and automation files (`make.bat` and `Makefile`) to build the documentation.

* Add requests_mock to requirements and fix filename typo

A new dependency, `requests_mock`, has been added to the `requirements.txt` file. Also, a typo in the filename of the requirements file located in the docs directory was corrected. It was previously named `requirments.txt` and has now been renamed to `requirements.txt`.

* Convert documentation from RST to Markdown

The documentation files `index.rst` and `README.rst` have been deleted and replaced by their Markdown equivalents `index.md` and `README.md`. The conversion was performed to improve readability and consistency, particularly in regard to the handling of links and images.

* Convert documentation from RST to Markdown

The documentation files `index.rst` and `README.rst` have been deleted and replaced by their Markdown equivalents `index.md` and `README.md`. The conversion was performed to improve readability and consistency, particularly in regard to the handling of links and images.

* Update Sphinx extensions and downgrade Python version

The Sphinx extensions have been updated in the documentation requirements and configuration section of the docs. "sphinx-autodoc2" has been added to the requirements while "sphinx.ext.autodoc" has been enabled in the configuration. Additionally, Python version used for building has been downgraded from 3.12 to 3.9.

* Update documentation configuration and content

In the configuration file, the release number is commented out and in the markdown file, the autoclass path is corrected for Sphinx to generate the project documentation accurately.

* Add github-app-handler to requirements

In this commit, the github-app-handler module has been added to the requirements.txt document. This is necessary to handle the integration of the GitHub application and the requirements file ensures all required modules are installed for the application to function properly.

* Update docs configuration and content

Modified docs/conf.py to replace sphinx-autodoc2 with autodoc2 and set the appropriate configurations, and changed the html theme. Also updated docs/index.md to use autodoc2-object and amended the reference link.

* style: format code with Black, isort and Ruff Formatter

This commit fixes the style issues introduced in bf5a99c according to the output
from Black, isort and Ruff Formatter.

Details: #229

---------

Co-authored-by: Heitor Polidoro <[email protected]>
Co-authored-by: deepsource-autofix[bot] <62050782+deepsource-autofix[bot]@users.noreply.github.com>

.readthedocs.yaml

@@ -8,11 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
-    # You can also specify other tool versions:
-    # nodejs: "20"
-    # rust: "1.70"
-    # golang: "1.20"
+    python: "3.9"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
@@ -30,6 +26,6 @@ sphinx:
 # Optional but recommended, declare the Python requirements required
 # to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#   install:
-#     - requirements: docs/requirements.txt
+python:
+ install:
+   - requirements: docs/requirements.txt

README.md

@@ -7,6 +7,8 @@ A handler helper to create GitHub App easily
 <br>
 [![Latest Version](https://img.shields.io/github/v/release/heitorpolidoro/github-app-handler?label=Latest%20Version)](https://github.com/heitorpolidoro/github-app-handler/releases/latest)
 ![GitHub Release Date](https://img.shields.io/github/release-date/heitorpolidoro/github-app-handler)
+[![Documentation Status](https://readthedocs.org/projects/github-app-handler/badge/?version=latest)](https://github-app-handler.readthedocs.io/en/latest/?badge=latest)
+<br>
 ![GitHub commits since latest release (by SemVer including pre-releases)](https://img.shields.io/github/commits-since/heitorpolidoro/github-app-handler/latest)
 ![GitHub last commit](https://img.shields.io/github/last-commit/heitorpolidoro/github-app-handler)
 <br>

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+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,45 @@
+"""
+Configuration file for the Sphinx documentation builder.
+
+For the full list of built-in configuration values, see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+-- Project information -----------------------------------------------------
+https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+"""
+
+project = "Github App Handler"
+copyright = "2024, Heitor Polidoro"
+author = "Heitor Polidoro"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "autodoc2",
+    # "sphinx.ext.intersphinx",
+    # "sphinx.ext.viewcode",
+    # "sphinxcontrib.bibtex",
+    #    "sphinx_panels",
+    # "sphinxext.rediraffe",
+    # "sphinxcontrib.mermaid",
+    # "sphinxext.opengraph",
+]
+myst_enable_extensions = ["colon_fence"]
+
+# Autodoc2 Configuration
+autodoc2_render_plugin = "myst"
+autodoc2_packages = ["../githubapp"]
+autodoc2_hidden_objects = ["inherited", "dunder", "private"]
+autodoc2_sort_names = True
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/index.md

@@ -0,0 +1,29 @@
+{include} ../README.md
+# My nifty title
+
+Some **text**!
+
+:::{admonition} Here's my title
+:class: tip
+
+Here's my admonition content.{sup}`1`
+:::
+
+(header-label)=
+# A header
+
+[My rehference](#header-label)
+
+### Content
+```{toctree}
+:maxdepth: 2
+
+Home <self>
+apidocs/index
+```
+
+```{autodoc2-object} githubapp.events.event.Event
+render_plugin = "myst"
+no_index = true
+```
+

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
+
+%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.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,7 @@
+sphinx==7.3.7
+myst_parser==3.0.1
+sphinx-autodoc2==0.5.0
+github-app-handler==0.28.4
+
+sphinx_rtd_theme==2.0.0
+readthedocs-sphinx-search==0.3.2

requirements.txt

@@ -1,2 +1,3 @@
 PyGithub==2.3.0
 pyyaml==6.0.1
+requests_mock==1.12.1