» 文档与笔记利器 reStructuredText 和 Sphinx Wow! Ubuntu

2023-10-17 17:50

本文主要是介绍» 文档与笔记利器 reStructuredText 和 Sphinx Wow! Ubuntu,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

» 文档与笔记利器 reStructuredText 和 Sphinx Wow! Ubuntu

» 文档与笔记利器 reStructuredText 和 Sphinx Wow! Ubuntu

文档与笔记利器 reStructuredText 和 Sphinx

28
2011
# 作者: 投稿/转载 / 本文采用 CC BY-NC-SA 2.5协议授权,转载请注明 本文链接。

本文转载自七星庐 [ 原文:文档与笔记利器reStructuredText和Sphinx / 作者 muzuiget ]

关于制作文档和笔记这种事,我已经纠结了很久,网上解决方案也一大推,我试过几样,ScrapBook 和 Zotero,编辑不太方便,同步麻烦。Google Note 过于格式简单,现在也不更新了,Google Docs又有点杀鸡用牛刀。还有传得很神奇的 Evernote 跟 Onenote,我压根没兴趣去用。

因为我的笔记大多都是自己写出来,整理出来的,就是精简成自己能看得懂的几段文字而已。我的要求无非这几样:主要是纯文本、工具开源、能同步和备份。

选择纯文本保存,我需要一个预定义格式,让笔记看起来有模有样,编辑器还能有简单代码高亮的,于是我在这个轻量级标记语言的维基页面观望好久。

Wiki也是一种不错方案,但是要搭服务器,不用服务器的也免不了各种配置,各种wiki系统的格式也不同。又研究了reStructuredText,发现阅读性非常好,能转换的格式也非常多。

vim就默认支持代码高亮了(rst扩展名),也能通过rst2html命令转换成的html,但是样式不太理想,我想应该有更漂亮的html生成器。于是我发现Sphinx这个工具,又当我发现其实这就是Python官方文档解决方案后。

我就做出最后决定了这一组合,reStructuredText作为标记语言,Sphinx作为生成工具。

预览

先来看看reStructuredText格式在vim的效果

生成html效果,就是python风格!

使用

只需安装python和sphinx即可。 安装python-sphinx这个包即可,自动解决依赖了,如果追新,则可以通过pypi来安装(也就是easy_install命令啦,不过要手动安装几个依赖库)。

安装后,应该会有sphinx-quickstart这个命令了。先新建一个空目录,这个目录会放置你的笔记

muzuiget:~$ mkdir note
muzuiget:~$ cd note/
muzuiget:~/note$ sphinx-quickstart

会问你N个问题,一般来说,只需要填四个地方,其余的都直接回车就行了

  1. Project name: Muzuiget Note
  2. Author name(s): muzuiget
  3. Project version: 1
  4. Project release [1]: 1

加粗的是我填的,最后的两个发布号跟先跟版本号一样就行了,这个可以以后再改的。然后这个目录的内容就是这样

muzuiget:~/note$ tree .
.
|-- _build
|-- conf.py
|-- index.rst
|-- make.bat
|-- Makefile
|-- _static
`-- _templates3 directories, 4 files

然后你可以用文本编辑器打开 index.rst 这个文件,如果用vim,就发现有代码高亮啦。暂时不用改什么,接着运行

muzuiget:~/note$ make html

然后用浏览器打开 _build/html/index.html 你会看到,舒服漂亮的python式文档出现鸟。

添加内容

当然现在什么内容也没有,现在你就可以向 index.rst 添加内容就行了。 至于reStructuredText的语法,reStructuredText、Sphinx、Python都有简单的教程

  1. reStructuredText A ReStructuredText Primer
  2. Sphinx reStructuredText Primer
  3. Python reStructuredText Primer

这几个链接的html本身就是reStructuredText写出来的,比如第一个链接的源代码,另存到为 quickstart.rst,放到 index.rst 的统一目录下。然后修改 index.rst,就加一行

.. toctree:::maxdepth: 2quickstart.rst

注意“quickstart.rst”中的“q”和“ :maxdepth: 2”的冒号在同一列,保存,然后重新

muzuiget:~/note$ make html

再次刷新 _build/html/index.html,你就看到新的内容了,很简单吧。除了html外,sphinx也支持其它格式,直接运行make就能看到参数了。

ReStructuredText资料

下一步问题就是学习reStructuredText来编写规范的文档和笔记了,reStructuredText官方有个快速参考。而可供参考的实际例子更加多了,Sphinx的文档和Python文档就是非常规范了,页面旁边有个“Show Source”链接,还不够,Sphinx上还有个列表。

其实之前的sphinx-quickstart这个命令主要是创建了了 conf.py 这个文件,里面就是输出html或其它格式的配置,可以参考Sphinx文档来修改,定制性相当得高,还内置几种主题。这个方面还大家慢慢研究吧。

同步

对了,如何同步呢?还用多想,直接把笔记文件夹扔到Dropbox得了,就这么简单。在Bitbucket搭个私有仓库也行。

posted on 2013-01-09 11:12  lexus 阅读( ...) 评论( ...) 编辑 收藏

转载于:https://www.cnblogs.com/lexus/archive/2013/01/09/2852501.html

这篇关于» 文档与笔记利器 reStructuredText 和 Sphinx Wow! Ubuntu的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/226977

相关文章

Python操作PDF文档的主流库使用指南

《Python操作PDF文档的主流库使用指南》PDF因其跨平台、格式固定的特性成为文档交换的标准,然而,由于其复杂的内部结构,程序化操作PDF一直是个挑战,本文主要为大家整理了Python操作PD... 目录一、 基础操作1.PyPDF2 (及其继任者 pypdf)2.PyMuPDF / fitz3.Fre

springboot自定义注解RateLimiter限流注解技术文档详解

《springboot自定义注解RateLimiter限流注解技术文档详解》文章介绍了限流技术的概念、作用及实现方式,通过SpringAOP拦截方法、缓存存储计数器,结合注解、枚举、异常类等核心组件,... 目录什么是限流系统架构核心组件详解1. 限流注解 (@RateLimiter)2. 限流类型枚举 (

C#监听txt文档获取新数据方式

《C#监听txt文档获取新数据方式》文章介绍通过监听txt文件获取最新数据,并实现开机自启动、禁用窗口关闭按钮、阻止Ctrl+C中断及防止程序退出等功能,代码整合于主函数中,供参考学习... 目录前言一、监听txt文档增加数据二、其他功能1. 设置开机自启动2. 禁止控制台窗口关闭按钮3. 阻止Ctrl +

Java docx4j高效处理Word文档的实战指南

《Javadocx4j高效处理Word文档的实战指南》对于需要在Java应用程序中生成、修改或处理Word文档的开发者来说,docx4j是一个强大而专业的选择,下面我们就来看看docx4j的具体使用... 目录引言一、环境准备与基础配置1.1 Maven依赖配置1.2 初始化测试类二、增强版文档操作示例2.

Ubuntu 24.04启用root图形登录的操作流程

《Ubuntu24.04启用root图形登录的操作流程》Ubuntu默认禁用root账户的图形与SSH登录,这是为了安全,但在某些场景你可能需要直接用root登录GNOME桌面,本文以Ubuntu2... 目录一、前言二、准备工作三、设置 root 密码四、启用图形界面 root 登录1. 修改 GDM 配

如何在Ubuntu 24.04上部署Zabbix 7.0对服务器进行监控

《如何在Ubuntu24.04上部署Zabbix7.0对服务器进行监控》在Ubuntu24.04上部署Zabbix7.0监控阿里云ECS服务器,需配置MariaDB数据库、开放10050/1005... 目录软硬件信息部署步骤步骤 1:安装并配置mariadb步骤 2:安装Zabbix 7.0 Server

Ubuntu如何分配​​未使用的空间

《Ubuntu如何分配​​未使用的空间》Ubuntu磁盘空间不足,实际未分配空间8.2G因LVM卷组名称格式差异(双破折号误写)导致无法扩展,确认正确卷组名后,使用lvextend和resize2fs... 目录1:原因2:操作3:报错5:解决问题:确认卷组名称​6:再次操作7:验证扩展是否成功8:问题已解

Java操作Word文档的全面指南

《Java操作Word文档的全面指南》在Java开发中,操作Word文档是常见的业务需求,广泛应用于合同生成、报表输出、通知发布、法律文书生成、病历模板填写等场景,本文将全面介绍Java操作Word文... 目录简介段落页头与页脚页码表格图片批注文本框目录图表简介Word编程最重要的类是org.apach

Python Pillow 库详解文档(最新推荐)

《PythonPillow库详解文档(最新推荐)》Pillow是Python中最流行的图像处理库,它是PythonImagingLibrary(PIL)的现代分支和继承者,本文给大家介绍Pytho... 目录python Pillow 库详解文档简介安装核心模块架构Image 模块 - 核心图像处理基本导入

C#实现将Office文档(Word/Excel/PDF/PPT)转为Markdown格式

《C#实现将Office文档(Word/Excel/PDF/PPT)转为Markdown格式》Markdown凭借简洁的语法、优良的可读性,以及对版本控制系统的高度兼容性,逐渐成为最受欢迎的文档格式... 目录为什么要将文档转换为 Markdown 格式使用工具将 Word 文档转换为 Markdown(.