Skip to content

Commit da994b6

Browse files
JE-ChenJE-Chen
authored
Merge pull request #35 from Integration-Automation/dev
Update docs
2 parents b06d43f + 9c912cd commit da994b6

33 files changed

Lines changed: 6191 additions & 219 deletions

‎README.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -494,5 +494,3 @@ MailThunder/
494494
## License
495495

496496
This project is licensed under the [MIT License](LICENSE).
497-
498-
Copyright (c) 2021 JE-Chen

‎docs/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# MailThunder Documentation
2+
3+
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
4+
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
5+
[![PyPI](https://img.shields.io/pypi/v/je_mail_thunder)](https://pypi.org/project/je-mail-thunder/)
6+
[![Read the Docs](https://readthedocs.org/projects/mailthunder/badge/?version=latest)](https://mailthunder.readthedocs.io/)
7+
[![Main README](https://img.shields.io/badge/Main-README-green.svg)](../README.md)
8+
[![GitHub](https://img.shields.io/badge/GitHub-Repository-black.svg)](https://github.com/Integration-Automation/MailThunder)
9+
10+
This directory contains the [Read the Docs](https://readthedocs.io/) Sphinx documentation source for **MailThunder**.
11+
12+
For the full project overview, see the [Main README](../README.md).
13+
14+
---
15+
16+
## Documentation Structure
17+
18+
```
19+
docs/
20+
README.md # This file
21+
Makefile # Unix build script
22+
make.bat # Windows build script
23+
requirements.txt # Sphinx dependencies
24+
source/
25+
conf.py # Sphinx configuration
26+
index.rst # Root page (toctree entry point)
27+
docs/
28+
Eng/ # English documentation
29+
eng_index.rst # Overview & architecture
30+
installation.rst # Installation guide
31+
authentication.rst # Authentication setup
32+
send_google_mail.rst # Sending emails (SMTP)
33+
read_google_mail.rst # Reading emails (IMAP)
34+
scripting_engine.rst # JSON scripting engine
35+
project_templates.rst # Project template scaffolding
36+
cli.rst # Command-line interface
37+
socket_server.rst # TCP socket server
38+
package_manager.rst # Dynamic package loader
39+
logging.rst # Logging system
40+
exceptions.rst # Custom exceptions
41+
Zh/ # 繁體中文文件
42+
zh_index.rst # 總覽與架構
43+
installation.rst # 安裝指南
44+
authentication.rst # 認證設定
45+
send_google_mail.rst # 寄送郵件 (SMTP)
46+
read_google_mail.rst # 讀取郵件 (IMAP)
47+
scripting_engine.rst # JSON 腳本引擎
48+
project_templates.rst # 專案模板
49+
cli.rst # 命令列介面
50+
socket_server.rst # Socket 伺服器
51+
package_manager.rst # 套件管理器
52+
logging.rst # 日誌記錄
53+
exceptions.rst # 例外處理
54+
API/ # API reference
55+
api_index.rst # Public exports & module map
56+
smtp_api.rst # SMTPWrapper API
57+
imap_api.rst # IMAPWrapper API
58+
executor_api.rst # Executor API
59+
utils_api.rst # Utility functions API
60+
```
61+
62+
---
63+
64+
## Building Locally
65+
66+
```bash
67+
pip install -r docs/requirements.txt
68+
cd docs
69+
make html # Linux / macOS
70+
make.bat html # Windows
71+
```
72+
73+
Open `docs/build/html/index.html` in your browser.
74+
75+
---
76+
77+
## Read the Docs Configuration
78+
79+
Configured via `.readthedocs.yaml` in the project root:
80+
81+
| Setting | Value |
82+
|---------|-------|
83+
| Build OS | `ubuntu-22.04` |
84+
| Python | `3.11` |
85+
| Sphinx config | `docs/source/conf.py` |
86+
| Theme | `sphinx-rtd-theme` |

‎docs/source/conf.py‎

Lines changed: 9 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,10 @@
11
# Configuration file for the Sphinx documentation builder.
22
#
3-
# This file only contains a selection of the most common options. For a full
4-
# list see the documentation:
3+
# For the full list of configuration options see:
54
# https://www.sphinx-doc.org/en/master/usage/configuration.html
65

76
# -- Path setup --------------------------------------------------------------
87

9-
# If extensions (or modules to document with autodoc) are in another directory,
10-
# add these directories to sys.path here. If the directory is relative to the
11-
# documentation root, use os.path.abspath to make it absolute, like shown here.
12-
#
138
import os
149
import sys
1510
from pathlib import Path
@@ -26,27 +21,22 @@
2621

2722
# -- General configuration ---------------------------------------------------
2823

29-
# Add any Sphinx extension module names here, as strings. They can be
30-
# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
31-
# ones.
3224
extensions = []
3325

34-
# Add any paths that contain templates here, relative to this directory.
3526
templates_path = ["_templates"]
3627

37-
# List of patterns, relative to source directory, that match files and
38-
# directories to ignore when looking for source files.
39-
# This pattern also affects html_static_path and html_extra_path.
4028
exclude_patterns = []
4129

4230
# -- Options for HTML output -------------------------------------------------
4331

44-
# The theme to use for HTML and HTML Help pages. See the documentation for
45-
# a list of builtin themes.
46-
#
4732
html_theme = "sphinx_rtd_theme"
4833

49-
# Add any paths that contain custom static files (such as style sheets) here,
50-
# relative to this directory. They are copied after the builtin static files,
51-
# so a file named "default.css" will overwrite the builtin "default.css".
5234
html_static_path = ["_static"]
35+
36+
# -- Options for sphinx_rtd_theme --------------------------------------------
37+
38+
html_theme_options = {
39+
"navigation_depth": 4,
40+
"collapse_navigation": False,
41+
"titles_only": False,
42+
}

‎docs/source/docs/API/api_index.rst‎

Lines changed: 82 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,86 @@
1-
MailThunder API
1+
API Reference
2+
=============
3+
4+
This section provides the complete API reference for all public classes, methods,
5+
and functions in MailThunder.
6+
7+
Public Exports
8+
--------------
9+
10+
All public APIs are accessible from the top-level ``je_mail_thunder`` package:
11+
12+
.. code-block:: python
13+
14+
from je_mail_thunder import (
15+
# SMTP
16+
SMTPWrapper, # SMTP wrapper class
17+
smtp_instance, # Pre-created SMTP instance (or None)
18+
19+
# IMAP
20+
IMAPWrapper, # IMAP wrapper class
21+
imap_instance, # Pre-created IMAP instance (or None)
22+
23+
# Authentication
24+
set_mail_thunder_os_environ, # Set auth env vars
25+
get_mail_thunder_os_environ, # Get auth env vars
26+
mail_thunder_content_data_dict, # Global credential dict
27+
is_need_to_save_content, # Check if credentials need saving
28+
read_output_content, # Read mail_thunder_content.json
29+
write_output_content, # Write mail_thunder_content.json
30+
31+
# Executor
32+
execute_action, # Execute action list
33+
execute_files, # Execute multiple action files
34+
add_command_to_executor, # Register custom commands
35+
36+
# JSON
37+
read_action_json, # Read JSON action file
38+
39+
# File Utilities
40+
get_dir_files_as_list, # List directory files
41+
42+
# Project
43+
create_project_dir, # Scaffold project with templates
44+
)
45+
246
----
347

4-
.. toctree::
5-
:maxdepth: 4
48+
Module Map
49+
----------
650

7-
imap_api.rst
8-
smtp_api.rst
51+
.. list-table::
52+
:header-rows: 1
53+
:widths: 40 60
954

55+
* - Import Path
56+
- Description
57+
* - ``je_mail_thunder.smtp.smtp_wrapper``
58+
- ``SMTPWrapper`` class, ``smtp_instance``
59+
* - ``je_mail_thunder.imap.imap_wrapper``
60+
- ``IMAPWrapper`` class, ``imap_instance``
61+
* - ``je_mail_thunder.utils.executor.action_executor``
62+
- ``Executor`` class, ``execute_action()``, ``execute_files()``, ``add_command_to_executor()``
63+
* - ``je_mail_thunder.utils.save_mail_user_content.save_on_env``
64+
- ``set_mail_thunder_os_environ()``, ``get_mail_thunder_os_environ()``
65+
* - ``je_mail_thunder.utils.save_mail_user_content.mail_thunder_content_save``
66+
- ``read_output_content()``, ``write_output_content()``
67+
* - ``je_mail_thunder.utils.save_mail_user_content.mail_thunder_content_data``
68+
- ``mail_thunder_content_data_dict``, ``is_need_to_save_content()``
69+
* - ``je_mail_thunder.utils.json.json_file``
70+
- ``read_action_json()``, ``write_action_json()``
71+
* - ``je_mail_thunder.utils.json_format.json_process``
72+
- ``reformat_json()``
73+
* - ``je_mail_thunder.utils.file_process.get_dir_file_list``
74+
- ``get_dir_files_as_list()``
75+
* - ``je_mail_thunder.utils.project.create_project_structure``
76+
- ``create_project_dir()``
77+
* - ``je_mail_thunder.utils.package_manager.package_manager_class``
78+
- ``PackageManager`` class, ``package_manager``
79+
* - ``je_mail_thunder.utils.socket_server.mail_thunder_socket_server``
80+
- ``TCPServer``, ``TCPServerHandler``, ``start_autocontrol_socket_server()``
81+
* - ``je_mail_thunder.utils.logging.loggin_instance``
82+
- ``mail_thunder_logger``
83+
* - ``je_mail_thunder.utils.exception.exceptions``
84+
- All custom exception classes
85+
* - ``je_mail_thunder.utils.exception.exception_tags``
86+
- Error tag strings

0 commit comments

Comments
 (0)