notemanager 0.1.0__tar.gz

notemanager-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

notemanager-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: notemanager
+Version: 0.1.0
+Summary: Note manager with CLI daemon and WebUI, supporting rst, markdown and plain text notes
+Author-email: Kenneth Lee <kenneth-lee-2012@qq.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Kenneth-Lee/NoteManager
+Project-URL: Issues, https://github.com/Kenneth-Lee/NoteManager/issues
+Keywords: notes,note-management,markdown,rst,knowledge-base,webui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Editors
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: docutils>=0.20
+Requires-Dist: Markdown>=3.4
+Requires-Dist: pygments>=2.14
+Requires-Dist: watchdog>=3.0
+Dynamic: license-file
+
+# NoteManager
+
+## 一句话介绍
+
+NoteManager是一个基于命令行和WebUI的，以个人充分掌控信息，不被任何商业盈利目的绑定的笔记管理软件.
+
+## 初始设想
+
+我大部分时间用Python-Sphinx写我的笔记，在一些项目里，偶尔也会用markdown。Sphinx的好处是格式完整，比较适合写书，缺点是要考虑这是哪个主题的一部分，要多写不少额外的东西，关键是要看之前，还要编译一下，内容多了以后编译时间很长；Markdown的好处是简单快捷，适合临时写个笔记，不用考虑写的这个东西具体属于哪个章节，缺点是章节之间互相独立，除了用grep查找，检索比较麻烦。
+
+我也尝试过用Obsidian一类的工具去自动管理这些关联关系，但我还是觉得不好用，Obsidian那些关联图看着很Cool，其实对于检索内容没啥用。我更希望是：我输入一个关键字，自动帮我找到和这个关键字相关的文档，然后我开始编辑，编辑完了存盘，我就不用管了。我又不是编辑，信息记录进去就行了，其他的尽量我就不想介入。如果要处理这些信息，我也不打算提供插件，我的逻辑是：这不过是个数据库，你爱怎么处理它，你独立处理就是了，我的控制流和那个工具没有关系，这样你才具有所有的主动性。
+
+对于这样一个需求，NoteManager的作用主要就是建立索引，我也不绑定特定的格式，我先支持txt, rst和md格式，以后还可以增加更多的文本格式。NoteManager的工作就是按约定把里面的索引找出来，建立一个索引数据库。而每个文本文件本身，按照格式的约定，都渲染成html文件。这样，一方面你可以通过索引数据库找到文档，另一方面你也可以同时看到文档和它渲染后的结果。这样，作为笔记，它该做的就都做了。其他功能，就不是笔记软件本身的功能了。
+
+为此，我这里尽量不介入你的文件管理。你把你要管理的所有笔记都放同一个目录下，我在这个目录下创建一个.NoteManager子目录，在里面给你生成索引和html文件，不改变你任何内容，你不需要NoteManager了，你把这个目录删掉就是了。NoteManager后台可以动态监控你的修改，你用其他工具更新了目录中的笔记文件，我们就在后代给你动态更新索引。
+
+所以，我们不使用Sphinx那样的一次次重新生成静态索引的机制。我们把每个笔记都看作是独立的，里面有一组可以被别人索引的引用，都可以作为被搜索的对象，而其他文件，要不直接链接这个文件的某个位置，要不请求动态索引，我直接根据关键字动态计算是什么页面的什么位置，直接给你找出来。其他文件搜索，除了支持原来rst/md等文件的静态索引，我们也支持动态索引语法。也就是说，如果你没有指定确切的位置，索引某个关键字，我们的搜索是一段搜索NoteManager索引数据库的代码，你总可以从最新的更新中找到对应的定义。
+
+我们整个设想是一个用户的笔记，全部都在一个目录下，你分简单的目录建构以便拷贝就行了，其他随便放，反正最后我们都是通过索引找到它的。但用于有时会引入多个目录，以便实现不同的功能，比如有些目录是日常笔记，有些目录是某本Sphinx写的书。这样用户不会希望这两者的索引是在一起的，所以，我们还是有“Project（项目）”的概念，但我们不希望用户需要进入或者打开那个项目，然后才能控制那些笔记，因为用户的思路一闪即逝，笔记这种东西，还是尽快打开就开始记录，记录完了扔在那里，慢慢整理才好。所以，你可以创建很多项目，但其中有一个是默认项目，默认的操作都是在这个项目上，但你也可以立即指定项目进行查找或者修改。
+
+这样我们就有两种控制目录：一种是针对项目的.NoteManager，另一种是针对用户的.NoteManager。前者的用途我们介绍过了，而后者主要就是记住有哪些项目，以及一些全局的控制信息。
+
+## 用户界面
+
+NoteManager的用户界面是这样构思的：首先，我们对每个用户，创建了一个管理项目的后台，这个称为NoteManager Daemon，简称nmrd。这样，所有命令，无论你从哪里发出，都是由这个后台执行的，不会互相冲突。我们的NoteManager命令（简称nmr），都直接发到nmrd上，由nmrd执行。nmrd同时会启动一个webui界面，允许你在本机，或者在其他机器上直接管理所有工程。
+
+这样，我们实际上就有两个接口：命令行接口和WebUI接口。两个接口功能基本上是类似的，只是设计得更适合那个接口执行。比如，你要在命令行上立即编辑某个笔记，你用nmr search去找某个关键字，在命令行上会返回每个笔记文件的目录，允许你直接编辑那个文件。但同时，webui上也会显示所有的搜索结果，你可以直接在webui上点击这个链接，直接查看对应的文件。进入特定的笔记，在webui上你可以直接选择编辑，在webui上更新文件。而同时，如果你在命令行上编辑那个文件，监控功能也能在你保存以后，在webui上把你新的编辑更新进来。当然，有些功能只能在命令行上做，比如关掉nmrd。也有写功能只适合在webui上做，比如你在编辑某个笔记的时候，用Ctrl-V把某幅截图拷贝到笔记上。这个在命令行上要你把截图先保存成文件，然后在笔记上写对应的链接。这种工作就不适合在命令行上一步到位，而webui上就可以。
+
+用户可以灵活组合这两种操作，更快完成工作。
+
+我还写了一个手机软件：[本地管家](https://atomgit.com/Kenneth-Lee-2025/local_manager)，支持把html目录压缩成zip文件，可以在手机上直接查看。
+
+我们前面说了，你可以把工程的.NoteManager/html直接打包，这个目录就是可以当作一个完整的html网站使用。但这个在本地管家显示出来效果并不好，因为我们为了让PC好用，会增加越来越复杂的界面元素，而在手机上我们最多只是为了容易看，不是为了编辑它，所以我们会额外做了一个export功能（同样在命令行和webui上都提供），让你生成一个简单版本的.html.zip文件，可以在本地管家上完成除了编辑以外的所有阅读和查找功能。
+
+顺便说一句，如果你只是要分享几个md或者rst文件，而不是要生成html，本地管家是支持.md.zip和.rst.zip格式的。那种情况下，你甚至都不需要NoteManager的支持，可以直接把几个md或者rst文件压缩一下，直接在本地管家就可以查看渲染结果。
+
+我原来做了另一个rst/md的渲染工具：[markdown_quickview](https://atomgit.com/Kenneth-Lee-2025/markdown_quickview)，那个可以独立渲染某个md/rst文件，这个功能现在我合并到本工具上了。你可以用nmr view命令渲染某个rst/md文件，如果这个文件在管理的项目之内，这会直接使用渲染好的结果，如果不在，也能临时渲染一个文件供查看。后者和前者的唯一区别是后者不是个工程，所以你引用其他rst/md文件可能引用不了。
+
+## 安装
+
+### 方式一：正式安装（推荐）
+
+如果你已经把这个项目发布到 PyPI（或私有索引）：
+
+```bash
+pip install notemanager
+```
+
+### 方式二：本地开发安装（editable）
+
+在源码目录下：
+
+```bash
+pip install -e .
+```
+
+依赖：Python >= 3.10，自动安装 `docutils`、`Markdown`、`pygments`、`watchdog`。
+
+### 从源码生成安装包（wheel / sdist）
+
+在仓库根目录（含 `pyproject.toml`）执行：
+
+```bash
+pip install build
+python -m build
+```
+
+完成后在 `dist/` 目录会得到：
+
+| 文件 | 说明 |
+|------|------|
+| `notemanager-<版本>-py3-none-any.whl` | Wheel，可直接分发或 `pip install` |
+| `notemanager-<版本>.tar.gz` | 源码发行包（sdist），供索引或再次构建 |
+
+本地安装刚生成的 wheel 做验证：
+
+```bash
+pip install dist/notemanager-*-py3-none-any.whl
+```
+
+若需上传到 PyPI（需 [PyPI](https://pypi.org/) 账号与 API token）：
+
+```bash
+pip install twine
+twine check dist/*
+twine upload dist/*
+```
+
+上传前通常会先清理旧产物：`rm -rf dist/ build/ *.egg-info`，再重新执行 `python -m build`。
+
+## 使用
+
+### 启动
+
+```bash
+notemanager start
+# 或
+nmr start
+```
+
+Daemon 启动后自动开启 Web 控制面板，默认地址：http://localhost:19833
+
+### 添加监控目录
+
+```bash
+notemanager add /path/to/your/notes
+# 或
+nmr add /path/to/your/notes
+```
+
+添加后自动执行首次构建并开始监控文件变化。若目录较大，`nmr add` 会持续输出构建进度。
+
+### 可选界面美化插件（UI Plugin）
+
+默认不配置时，界面保持当前基础风格。
+
+若希望启用内置美化主题，请在项目根目录创建 `.nmrui.json`：
+
+```json
+{
+  "plugin": "modern"
+}
+```
+
+然后执行一次 `nmr rebuild` 即可生效。
+
+可通过下述配置关闭插件：
+
+```json
+{
+  "enabled": false
+}
+```
+
+### 其他命令
+
+```bash
+nmr status                  # 查看 daemon 状态和所有项目信息
+nmr list                    # 列出所有监控中的目录
+nmr remove <目录>           # 停止监控并删除生成的文件
+nmr default [工程]          # 设置/查看默认工程
+nmr stop                    # 停止 daemon
+```
+
+### 导出手机用 .html.zip（export）
+
+面向 [本地管家](https://atomgit.com/Kenneth-Lee-2025/local_manager) 等应用：在**临时目录独立渲染**工程内 `.md`/`.rst`，再打 zip，**不**打包工程下已有的 `.NoteManager/html`（避免与控制台复杂页混用，便于以后分别演进）。
+
+**页面特点**：仅保留渲染结果（KaTeX、Mermaid 等与控制台一致）；无侧栏、无「源文件 / 诊断」、不调用 Daemon。**首页（`index.html`）** 独占「查找」与文档树；**笔记页** 顶栏只有 **首页**（回到首页再查）和标题，本页目录用 `<details>` 折叠在同一页内，无弹层。**再查其他笔记**时请点 **首页**，保证手机上每次只呈现一个完整页面层次。
+
+**命令行**（需 Daemon 在线以解析 `-p` 工程，导出在本地执行）：
+
+```bash
+nmr export [-p 工程] [--output 路径.html.zip]
+```
+
+未指定 `--output` / `-o` 时，默认写入**当前工作目录**下 `<工程目录名>.html.zip`。
+
+**Web 控制台**：各项目行的「**导出ZIP**」按钮会向 `POST /api/export_zip`（JSON：`{"project": <工程下标>}`）请求 zip，浏览器下载得到同名 `.html.zip`。
+
+### 搜索、编辑与联动
+
+```bash
+nmr search <关键词> [-p 工程]
+```
+
+- 将搜索请求推送到 WebUI（自动跳到目标项目并显示结果）
+- 同时在命令行输出所有匹配结果对应的源文件绝对路径，便于复制后自行 `cd`
+
+```bash
+nmr searche <关键词> [-p 工程]
+```
+
+- 交互式选择搜索结果
+- 输入数字后直接用 `$EDITOR` 打开对应源文件（例如 `export EDITOR=vim` 或 `export EDITOR="code -w"`）
+
+```bash
+nmr view <文件路径.md|.rst|.txt>
+```
+
+- 若文件属于已管理项目：跳转到该文件对应的项目 HTML 页面
+- 若文件未纳入管理：临时渲染单文件页面（`/temp/...`）并跳转显示
+
+### Web 控制面板
+
+启动 daemon 后访问 http://localhost:19833 ，可以：
+
+- 查看所有监控目录及其状态
+- 添加/移除目录
+- 手动触发重建
+- **导出ZIP**：生成上述手机用 `.html.zip`
+- 进入项目页面浏览 HTML 输出（侧边栏 Home 回到该项目站点主页）
+- 需要回到管理界面时，在浏览器地址栏打开 http://localhost:19833/ 即可
+- 进入具体文档后，在「源文件」页签可用内置编辑器修改 `.md`/`.rst`/`.txt`，**保存并刷新渲染**；粘贴剪贴板中的截图可自动保存到源文件同目录并插入引用（详见 `docs/web-source-editor.md`）
+
+### 扫描格式与忽略规则
+
+- 受管理项目默认扫描并渲染：`.md`、`.rst`、`.txt`（txt 按段落简单渲染）。
+- 可在项目根创建 `.nmrignore` 跳过目录或文件（gitignore 风格子集）：
+  - `build/` 忽略目录及其下所有内容
+  - `*.draft.md` 忽略匹配文件
+  - `!notes/keep.txt` 反向包含（覆盖前面的忽略）
+
+### 可移植性
+
+每个被管理的目录下会生成 `.NoteManager/` 子目录，其中的 `html/` 目录是完整的可浏览站点。将整个 `.NoteManager/` 拷贝到任何有浏览器的地方都能使用，包括搜索功能。
+
+拷贝后的页面若**不是**通过控制台 Web 的 `/p/<工程号>/…` URL 打开，「源文件」页签会自动变为**只读纯文本**（不调用保存 API，避免报错）；在线编辑仅在本机通过控制台进入工程页面时可用。
+
+## 目录结构
+
+被管理目录下的 `.NoteManager/`：
+
+```
+.NoteManager/
+├── html/                   # 渲染后的 HTML，保持原目录结构
+├── index/
+│   ├── search_index.json   # 全文搜索索引
+│   └── ref_labels.json     # 交叉引用标签映射
+├── static/
+│   ├── notemanager.css
+│   └── notemanager.js
+└── status.json
+```
+
+全局配置在 `~/.NoteManager/`：
+
+```
+~/.NoteManager/
+├── config.json     # 监控目录列表和端口配置
+├── daemon.json     # daemon 运行时信息（PID、端口）
+└── daemon.log      # 后台日志
+```