Merge pull request #29 from cocolato/dev

Merge dev

.gitignore

@@ -11,3 +11,6 @@ test.py
 
 dist/
 .pdm-python
+
+# Sphinx documentation
+docs/build/

.readthedocs.yaml

@@ -0,0 +1,15 @@
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+sphinx:
+  configuration: docs/source/conf.py

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     = source
+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/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+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.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%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,45 @@
+# This file is @generated by PDM.
+# Please do not edit it manually.
+
+alabaster==0.7.13
+babel==2.14.0
+certifi==2024.2.2
+charset-normalizer==3.3.2
+colorama==0.4.6; sys_platform == "win32"
+dill==0.3.7
+docutils==0.17.1
+exceptiongroup==1.2.0; python_version < "3.11"
+flake8==5.0.4
+idna==3.6
+imagesize==1.4.1
+importlib-metadata==4.2.0; python_version < "3.8"
+iniconfig==2.0.0
+jinja2==3.1.3
+markupsafe==2.1.5
+mccabe==0.7.0
+packaging==23.2
+pluggy==1.2.0
+pycodestyle==2.9.1
+pyflakes==2.5.0
+pygments==2.17.2
+pytest==7.4.4
+pytest-order==1.2.0
+pytz==2024.1; python_version < "3.9"
+requests==2.31.0
+setuptools==68.0.0
+snowballstemmer==2.2.0
+sphinx==4.3.2
+sphinx-copybutton==0.5.2
+sphinx-rtd-theme==1.3.0
+sphinx-tabs==3.4.5
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+tomli==2.0.1; python_version < "3.11"
+typing-extensions==4.7.1; python_version < "3.8"
+urllib3==2.0.7
+zipp==3.15.0; python_version < "3.8"

docs/source/conf.py

@@ -0,0 +1,40 @@
+# 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 = 'pydumpling'
+copyright = '2024, cocolato'
+author = 'cocolato'
+release = '0.1.4'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+html_context = {
+    "display_github": True,  # Integrate GitHub
+    "github_user": "cocolato",  # Username
+    "github_repo": "pydumpling",  # Repo name
+    "github_version": "main",  # Version
+    "conf_py_path": "/source/",  # Path in the checkout to the docs root
+}
+
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx_tabs.tabs",
+    "sphinx_copybutton"
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+html_theme = "sphinx_rtd_theme"
+
+html_static_path = ['_static']
+html_logo = "_static/logo.png"
+html_favicon = "_static/favicon.png"
+html_title = "Pydumpling Documentation"
+html_show_sourcelink = False

docs/source/index.rst

@@ -0,0 +1,55 @@
+Welcome to Pydumpling
+=======================
+
+.. image:: https://img.shields.io/pypi/dm/pydumpling
+   :alt: PyPI - Downloads
+   :target: https://pypi.org/project/pydumpling/
+
+.. image:: https://img.shields.io/pypi/v/pydumpling
+   :alt: PyPI - Version
+   :target: https://pypi.org/project/pydumpling/
+
+.. image:: https://img.shields.io/github/stars/cocolato/pydumpling
+   :alt: GitHub Repo stars
+   :target: https://github.com/cocolato/pydumpling/
+
+
+
+It's a fork/optimized version from `elifiner/pydump`_ .The main optimization points are:
+
+* Save the ``Python traceback`` anywhere, not just when it's an exception.
+* Optimize code structure && remove redundant code
+* fix bug in python2.7 && support python3.10+
+* supported more pdb command
+* provides command line tools
+
+.. _elifiner/pydump: https://github.com/elifiner/pydump
+
+Pydumpling writes the ``python current traceback`` into a file and
+can later load it in a Python debugger. It works with the built-in
+pdb and with other popular debuggers (`pudb`_, `ipdb`_ and `pdbpp`_).
+
+.. _pudb: https://github.com/inducer/pudb
+.. _ipdb: https://github.com/gotcha/ipdb
+.. _pdbpp: https://github.com/pdbpp/pdbpp
+
+Why use Pydumpling?
+-------------------
+
+* We usually use ``try... except ... `` to catch exceptions that occur in our programs, but do we really know why they occur?
+* When your project is running online, you suddenly get an unexpected exception that causes the process to exit. How do you reproduce this problem?
+* Not enough information in the logs to help us pinpoint online issues?
+* If we were able to save the exception error and then use the debugger to recover the traceback at that time, we could see the entire stack variables along the traceback as if you had caught the exception at the local breakpoint.
+
+
+User's Guide
+------------
+
+Get started with :doc:`installation`
+and then get an overview with the :doc:`tutorial` that shows how to use.
+
+.. toctree::
+   :maxdepth: 4
+
+   installation
+   tutorial

docs/source/installation.rst

@@ -0,0 +1,27 @@
+Installation
+=============
+
+Python Version
+---------------
+
+Python version: >=3.7
+
+
+Install
+-------
+
+Not published in pypi yet, so use the `.whl` file install pydumpling in the dist path.
+
+.. tabs::
+
+   .. group-tab:: Linux/macOS
+
+      .. code-block:: text
+
+         $ pip3 install pydumpling
+
+   .. group-tab:: Windows
+
+      .. code-block:: text
+
+         > pip install pydumpling