From c38cd70f7ecc3245474b194d88e018e26c139bc0 Mon Sep 17 00:00:00 2001 From: Wu Zhenyu Date: Sat, 11 Mar 2023 14:01:59 +0800 Subject: [PATCH] :memo: Add document --- .gitignore | 1 + .readthedocs.yaml | 21 +++++++++++ LICENSE | 0 README.md | 0 docs/conf.py | 51 ++++++++++++++++++++++++++ docs/index.md | 25 +++++++++++++ DEV_README.md => docs/resources/dev.md | 25 +++++++------ pyproject.toml | 7 +++- 8 files changed, 116 insertions(+), 14 deletions(-) mode change 100755 => 100644 .gitignore create mode 100644 .readthedocs.yaml mode change 100755 => 100644 LICENSE mode change 100755 => 100644 README.md create mode 100644 docs/conf.py create mode 100644 docs/index.md rename DEV_README.md => docs/resources/dev.md (95%) diff --git a/.gitignore b/.gitignore old mode 100755 new mode 100644 index 0aebd15..623188d --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ _version.py +_metainfo.py .vscode/ test_output/mag* test_output/select* diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..74b1cee --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,21 @@ +# https://docs.readthedocs.io/en/stable/config-file/v2.html +--- +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3" + jobs: + pre_build: + - pip install . + +sphinx: + configuration: docs/conf.py + +formats: + - pdf + +python: + install: + - requirements: docs/requirements.txt diff --git a/LICENSE b/LICENSE old mode 100755 new mode 100644 diff --git a/README.md b/README.md old mode 100755 new mode 100644 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..78f1742 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,51 @@ +r"""Configure the Sphinx documentation builder. + +https://www.sphinx-doc.org/en/master/usage/configuration.html +""" +from mulimgviewer import __version__ as version # type: ignore +from mulimgviewer._metainfo import author, copyright, project # type: ignore + +__all__ = ["version", "author", "copyright", "project"] + +# -- 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. + +# -- Project information ----------------------------------------------------- +language = "en" + +# -- 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", + "myst_parser", + "sphinxcontrib.eval", +] + +myst_heading_anchors = 3 +myst_title_to_header = True + +# 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. +# + +# 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"] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..236bc7f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,25 @@ + +```{toctree} +--- +hidden: +glob: +caption: resources +--- +resources/* +``` + +```{toctree} +--- +hidden: +caption: Index +--- +genindex +modindex +search +``` + +```{include} ../README.md +--- +relative-docs: docs +--- +``` diff --git a/DEV_README.md b/docs/resources/dev.md similarity index 95% rename from DEV_README.md rename to docs/resources/dev.md index c2f39c7..c37062f 100644 --- a/DEV_README.md +++ b/docs/resources/dev.md @@ -1,5 +1,6 @@ # MulimgViewer开发指南 -# 0. 加入我们吧！ + +## 0. 加入我们吧！ **初衷**：目前的市面上的图像浏览器不能同时显示多张图像。2020.8.10诞生的MulimgViewer，希望可以让大家方便地进行多张图像的显示和比较。恍惚一世，希望能在这个世界留下痕迹。 **定位**：MulimgViewer，即multi-image viewer。该软件**核心功能**是：多张图像并行显示、比较。 @@ -28,7 +29,7 @@ 3. 正常的开发流程：fork到自己本地->新建一个分支->实现功能->自行调试成功->合并到主分支。 4. 如果您希望深度地、持续地参与到项目的开发中，可以邮件(liujiawei18@mails.ucas.ac.cn)联系我。我会邀请您开发此软件，您可以获得直接访问该项目的权限，这有利于快速及时地更新主分支。 -# 1. 文件说明 +## 1. 文件说明 项目框架： ``` MulimgViewer @@ -56,15 +57,15 @@ MulimgViewer - README.md # 12. 用户readme - DEV_README.md # 13. 开发readme ``` -# 2. 开发流程 -## 2.1 GUI的创建 +## 2. 开发流程 +### 2.1 GUI的创建 GUI使用[wxFormBuilder](https://github.com/wxFormBuilder/wxFormBuilder)创建。wxFormBuilder的安装： 1. window平台可以直接下载[exe](https://github.com/wxFormBuilder/wxFormBuilder/releases)。 2. linux平台可以下载`.deb`，或者使用`.flatpak`。 3. ubuntu18.04下的安装，可以见[参考](https://nachifur.blog.csdn.net/article/details/107702485). 4. 目前MulimgViewer使用的wxFormBuilder版本为：v3.10.1。大家也可以使用最新的版本。 -## 2.2 编写实现GUI的回调函数 +### 2.2 编写实现GUI的回调函数 为了分离GUI和功能实现，对于`MulimgViewer/gui`路径下的文件，不建议手动直接修改。具体的操作如下： 1. wxFormBuilder创建GUI文件`MulimgViewer/gui/main.fbp`。 2. 使用自动生成代码，生成`MulimgViewer/gui/main_gui.py`。只需在wxFormBuilder的GUI中，点击代码生成按钮即可生成`.py`。 @@ -77,22 +78,22 @@ GUI使用[wxFormBuilder](https://github.com/wxFormBuilder/wxFormBuilder)创建 * [wxpython doc](https://docs.wxpython.org/index.html) * [wxpython 自定义事件、线程安全、多线程交互、版本更新](https://nachifur.blog.csdn.net/article/details/124809333) -## 2.3 跨平台的支持 +### 2.3 跨平台的支持 MulimgViewer的所有功能均采用python编写，这保证了跨平台的使用。但是windows和linux的路径是有区别的。**直接使用`D:\ncfey\Desktop\`，是非常糟糕的**，这会破坏跨平台。因为我们**强烈建议**使用： ``` from pathlib import Path ``` [pathlib使用说明](https://zhuanlan.zhihu.com/p/13978333) -## 2.4 readme的维护 +### 2.4 readme的维护 * 当您提出一个issue，或者决定参与该项目的开发，可以添加到[README.md-7. 未来增强功能](https://github.com/nachifur/MulimgViewer#7.0)以及[wiki-7. Future enhancements](https://github.com/nachifur/MulimgViewer/wiki#7.0)。 * 当您完成一个功能的时候，可以在issue中添加该功能的`md`说明。在下一个版本release的时候，我们会更新`README.md`（仅包含最新release版本的功能介绍）。 * 当您完成一个功能的时候，可以添加到[README.md-8. 致谢](https://github.com/nachifur/MulimgViewer#7.0)以及[wiki-8. Acknowledgements](https://github.com/nachifur/MulimgViewer/wiki#8.0)。 -# 3. Release +## 3. Release 我们的下一个release版本的计划可见[projects](https://github.com/nachifur/MulimgViewer/projects?type=classic)。 -## 3.1 window的打包 +### 3.1 window的打包 1. 安装： ``` pip install wxpython pillow pytest-shutil numpy requests @@ -112,10 +113,10 @@ pyinstaller -D -w -i mulimgviewer.ico --add-data "mulimgviewer.ico;." --add-data ``` * 使用createinstall打包成可安装的`.exe`。[createinstall使用](https://blog.csdn.net/qq_41811438/article/details/103092610) -## 3.2 linux/ios/arm等平台的打包 +### 3.2 linux/ios/arm等平台的打包 ubuntu的打包可以使用`dpkg`。个人目前不了解其他平台的打包，期待大家可以帮助打包MulimgViewer！献上最真诚的感谢！ -## 3.3 命名 +### 3.3 命名 ``` MulimgViewer_3.9.3_win10_amd64_Portable.exe MulimgViewer_3.9.3_win10_amd64_Setup.exe @@ -123,7 +124,7 @@ MulimgViewer_3.9.3_ubuntu_amd64.deb MulimgViewer_3.9.3_ios_amd64.ipa ``` -## 3.4 镜像维护 +### 3.4 镜像维护 我们目前支持以下两个镜像，release版本需要推送到这两个站点： * [**国内gitee镜像项目**](https://gitee.com/nachifur/MulimgViewer) * [**果壳OpenCas镜像项目**](https://github.com/opencas/MulimgViewer) diff --git a/pyproject.toml b/pyproject.toml index e3768e7..f5ccee0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,5 @@ [build-system] -requires = ["setuptools >= 45", "setuptools_scm[toml] >= 6.2"] +requires = ["setuptools_scm[toml] >= 6.2", "setuptools-generate"] build-backend = "setuptools.build_meta" # https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html @@ -59,7 +59,7 @@ Download = "https://github.com/nachifur/mulimgviewer/releases" "Bug Report" = "https://github.com/nachifur/mulimgviewer/issues" Source = "https://github.com/nachifur/mulimgviewer" -[project.scripts] +[project.gui-scripts] mulimgviewer = "mulimgviewer.__main__:main" [tool.setuptools.dynamic.dependencies] @@ -71,6 +71,9 @@ file = "requirements/dev.txt" [tool.setuptools_scm] write_to = "src/mulimgviewer/_version.py" +[tool.setuptools-generate] +write-to = "src/mulimgviewer/_metainfo.py" + [tool.black] # some code generated by wxFromBuilder is too long line-length = 240