Init english docs

Author: jondy

pyarmor/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)

pyarmor/docs/conf.py

@@ -0,0 +1,72 @@
+# 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 --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Pyarmor'
+copyright = '2025, Dashingsoft Corp.'
+author = 'Jondy Zhao'
+
+# The full version, including alpha/beta/rc tags
+release = '9.1.0'
+
+
+# -- 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.napoleon',
+    'sphinx.ext.graphviz',
+    'linuxdoc.rstFlatTable',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en_US'
+
+# 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 = 'nature'
+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']
+
+# The output format for Graphviz when building HTML files. This must
+# be either 'png' or 'svg'; the default is 'png'. If 'svg' is used, in
+# order to make the URL links work properly, an appropriate target
+# attribute must be set, such as "_top" and "_blank".
+graphviz_output_format = 'svg'

pyarmor/docs/zh/gendoc.py renamed to pyarmor/docs/gendoc.py

@@ -0,0 +1,25 @@
+.. Pyarmor documentation master file, created by
+   sphinx-quickstart on Thu Dec  5 18:30:56 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Pyarmor |version| Documentation
+===============================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Content
+
+   user/features
+   user/concepts
+   user/tutorials
+   user/man
+   user/configuration
+   user/examples
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

pyarmor/docs/index.rst

@@ -0,0 +1,203 @@
+===========
+ Proposals
+===========
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: top
+
+.. highlight:: console
+
+Features
+========
+
+.. _feature-1:
+
+1. 能够生成多种加密脚本，根据需要应用于不同的场景
+
+   加密后的脚本还是正常的 Python 脚本，可以被 Python 解释器正常解释执行
+
+   - 有的加密脚本，使用多种不可逆的加密模式，适用于算法保护
+   - 有的加密脚本，加密后性能和原来的脚本基本相当，适用于 Web 服务
+   - 有的加密脚本，可以继续使用其他工具，例如 Nuitka 等进行进一步的保护
+
+.. _feature-2:
+
+2. 多种不可逆的加密模式
+
+   转换部分 Python 语句块为 C 代码，生成不可逆的加密代码
+
+   重命名模块内部的函数，类，方法，属性，参数，变量等的名称
+
+.. _feature-3:
+
+3. 设置加密脚本有效期
+
+.. _feature-4:
+
+4. 绑定加密脚本到固定设备
+
+.. _feature-5:
+
+5. 保护字符串常量
+
+.. _feature-6:
+
+6. 自我保护功能
+
+   发现加密脚本被替换会退出执行
+
+   发现脚本中加密函数被替换会退出执行
+
+Concepts
+========
+
+加密脚本
+--------
+
+Pyarmor 能够生成 5 种不同类型的加密脚本
+
+- std: 标准型
+- ecc: 嵌入型
+- vmc: 虚拟嵌入型
+- mini: 迷你型
+- rft: 重构型
+
+下表列出每一种模式的主要特点和用途（设计目的）
+
+.. flat-table:: 表-1. 加密脚本类型表
+   :widths: 10 10 10 10 60
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - 加密类型
+     - 安全性 [#]_
+     - 运行速度 [#]_
+     - 扩展模块 [#]_
+     - 备注
+   * - 标准型
+     - 正常
+     - 正常
+     - 需要
+     - 能够设置加密脚本有效期和绑定加密脚本到固定设备，其他加密脚本类型都不具备此特性，适用于大多数的情况
+   * - 嵌入型
+     - 最高
+     - 正常
+     - 需要
+     - 通过转换 Python 语句块为 C 代码，实现更高程度的不可逆加密，同时能对字符串常量的进行很好保护，适用对算法类型的应用加密。性能和安全性均高，但是需要额外的 C 编译器，加密过程比较复杂
+   * - 虚拟嵌入型
+     - 较高
+     - 较慢
+     - 需要
+     - 是虚拟型加密的简化，转换部分 Python 语句块成为虚拟机器代码，而不是真正的 C 代码，这样就不需要 C 编译器，简化了加密配置
+   * - 迷你型
+     - 较低
+     - 很高
+     - 需要
+     - 不可逆程度较低，但是执行速度较高，适用于 Web 服务等类型
+   * - 重构型
+     - 最低
+     - 最高
+     - 不需要
+     - 和普通 Python 脚本完全一样，主要是对 Python 语句进行了重构，所以不需要额外的扩展模块，适用范围更广，包括用于 WASM，也可以继续使用任意工具，例如 Nuitka，Cython 等进一步处理
+
+.. rubric:: Notes
+
+.. [#] 安全性主要是指加密脚本的不可逆程度
+.. [#] 运行速度是指加密脚本的运行速度和没有加密之前的脚本运行速度的比较
+.. [#] 运行加密脚本是否需要额外的扩展模块，除了重构型脚本之外，其他类型的都需要
+
+
+下表从另外一个维度比较了各种加密脚本的特点
+
+.. flat-table:: 表-2. 不同加密脚本的比较表
+   :widths: 40 12 12 12 12 12
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Feature
+     - 标准型
+     - 嵌入型 [#pro]_
+     - 虚拟嵌入型 [#pro]_
+     - 迷你型
+     - 重构型
+   * - 是否需要额外的扩展模块
+     - :cspan:`3` Y
+     - N
+   * - 是否能够重命名模块中类/函数/方法/属性等名称 [#pro]_
+     - :cspan:`4` Y
+   * - 是否能够转换 Python 语句为 C 代码
+     - N
+     - Y [#pro]_
+     - Y [#pro]_  [#vmc]_
+     - :cspan:`1` N
+   * - 设置脚本有效期/绑定到固定设备/设置约束模式/自我保护功能
+     - Y
+     - :cspan:`3` N
+   * - 脚本的不可逆程度 [#pro]_
+     - ✫✫✫
+     - ✫✫✫✫✫
+     - ✫✫✫✫
+     - ✫✫
+     - ✫
+   * - 加密后运行的速度
+     - ✫✫✫
+     - ✫✫
+     - ✫
+     - ✫✫✫✫
+     - ✫✫✫✫✫
+   * - Python 解释器的支持
+     - :cspan:`3` 支持 CPython，或者提供 CPython API 的解释器
+     - 任意的 Python 脚本解释器，包括 IPython, WASM 等
+
+.. rubric:: Notes
+
+.. [#pro] 这些功能需要能够解锁不可逆加密模式的许可证
+.. [#vmc] 不是真正的转换成为 C 代码，而是虚拟指令
+
+.. seealso:: Pyarmor 的许可证类型
+
+选项
+----
+
+- 是否重构脚本，适用于所有加密脚本类型
+
+  重构的子选项
+
+  - builtin 是否重名
+  - argument 参数重命名模式
+
+- 重构规则表
+
+  仅用于处理无法自动重构的代码
+
+- 是否混淆字符串
+
+- 是否保护加密模块
+
+  如果该加密模式被替换，那么抛出保护异常
+
+- 是否保护加密函数
+
+  如果在调用之前发现加密函数被替换，那么抛出保护异常
+
+工程
+----
+
+工程是用来组织需要加密的脚本和如何加密脚本的选项集合
+
+许可证
+------
+
+Pyarmor 提供 5 种不同的许可证模块
+
+- Trial: 不能加密大脚本
+- Basic: 解锁对大脚本的加密功能
+- Pro: 除了解锁基础版功能外，还解锁不可逆的加密模式，包括 RFT, BCC, ECC, VMC 等
+- Group: 除了解锁专家版功能外，还支持在离线设备对脚本进行加密，其他类型的许可证都需要在线验证许可证
+- CI: 支持在 CI/CD 管线中使用专家版的功能
+
+.. note::
+
+   试用版和基础版不支持生成嵌入型，虚拟嵌入型和重构型脚本，但是可以生成标准型，迷你型脚本，不过这些脚本都没有进行重构

pyarmor/docs/proposals.rst

@@ -0,0 +1,7 @@
+===========
+ Platforms
+===========
+
+支持的 Python 版本，操作系统，CPU 架构
+
+支持的 Python 解释器，CPython, IPython, WASM 等等

pyarmor/docs/reference/platforms.rst

@@ -0,0 +1,10 @@
+========
+ Ranges
+========
+
+支持的有效值的范围
+
+譬如
+
+VMC 模式中 for 语句最大的嵌套层数目前支持的是 8 层
+VMC 模式中最大的变量数目是 2 的 32 次幂