1. 全栈程序员必看首页

rst和markdown_什么是RSA

全栈程序员-用户IM • • 未分类

rst和markdown_什么是RSA无论是写博客还是相关技术文档，都或多或少会接触到文档文本的编辑，txt不足以满足我们的需求，rst和md文档就应运而生。本博客系列文档主要使用rst文档编写，也有部分md文档，rst文档预览以及文档编译使用到Sphinx和ReadTheDocs，编辑器使用vscode，[vscode配置参考这里](https://taotaodiy.readthedocs.io/en/latest/env/vscode.html)。

大家好，又见面了，我是你们的朋友全栈君。如果您正在找激活码,请点击查看最新教程,关注关注公众号 “全栈程序员社区” 获取激活教程,可能之前旧版本教程已经失效.最新Idea2022.1教程亲测有效,一键激活。

Jetbrains全系列IDE稳定放心使用

RST 和 Markdown

关键词： vscode rst md sphinx 开发环境

无论是写博客还是相关技术文档，都或多或少会接触到文档文本的编辑，txt不足以满足我们的需求，rst和md文档就应运而生。
本博客系列文档主要使用rst文档编写，也有部分md文档，rst文档预览以及文档编译使用到Sphinx和ReadTheDocs，
编辑器使用vscode，vscode配置参考这里。

主要内容：

  • sphinx 环境配置
  • sphinx 基本使用
  • 文档格式转换
  • rst 语法
  • md 语法

文档参考：

最新地址： https://taotaodiy-linux.readthedocs.io/en/latest/env/rstRule.html

sphinx 环境配置

首先需要安装 vscode和安装插件reStructuredText

接着配置python环境

然后安装 sphinx

pip install sphinx

sphinx 使用

这里演示使用 sphinx 创建一个全新的sphinx工程。

sphinx-quickstart

新建目录 taotaodiy，新建一个 git 仓库，参考git使用。 当然也可以是空目录。然后在该目录下载执行sphinx-quickstart。

Windows可以使用cmd，先切换到该目录再执行sphinx-quickstart，也可以使用VSCode的终端。
Ubuntu就很容易了，命令行直接执行。输出如下：

root@bluseli:/home/share/taotaodiy# sphinx-quickstart
欢迎使用 Sphinx 3.2.1 快速配置工具。

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> 独立的源文件和构建目录（y/n） [n]: Y

The project name will occur in several places in the built documentation.
> 项目名称: taotaodiy
> 作者名称: bluseli
> 项目发行版本 []: 0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> 项目语种 [en]: zh_CN

创建文件 /home/share/taotaodiy/source/conf.py。
创建文件 /home/share/taotaodiy/source/index.rst。
创建文件 /home/share/taotaodiy/Makefile。
创建文件 /home/share/taotaodiy/make.bat。

完成：已创建初始目录结构。

You should now populate your master file /home/share/taotaodiy/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

执行成功，则配置成功。检查目录如下，其中：

工程目录

  • build 为项目编译输出（例如产生的.html）,
  • make.bat 为 Windows 下的批处理文件，类似与 Makefile ，在 Windows
    下编译项目。
  • source 为项目源文件（也就是我们编辑的 rst 文档，最终会生成 .html ）,
  • conf.py 为项目配置文件，后面我们根据这个配置文件修改主题等等。
  • index.rst 为所有 html 的索引页面。

编译 rst 文件

Ubuntu 直接在目录中执行 make html，然后 sphinx 会根据 Makefile 和
conf.py 编译项目， Windows 则，可以利用 VSCode 直接运行
conf.py，便可以编译并预览。预览的插件即为上面推荐的 reStructuredText 。

sphinx 不仅仅可以将我们编写的 rst 文档编译成 html
，其他形式的文件同样可以，具体看如下参数。

root@bluseli:/home/share/taotaodiy# make
Sphinx v3.2.1
Please use 'make target' where target is one of
html        to make standalone HTML files
dirhtml     to make HTML files named index.html in directories
singlehtml  to make a single large HTML file
pickle      to make pickle files
json        to make JSON files
htmlhelp    to make HTML files and an HTML help project
qthelp      to make HTML files and a qthelp project
devhelp     to make HTML files and a Devhelp project
epub        to make an epub
latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
latexpdf    to make LaTeX and PDF files (default pdflatex)
latexpdfja  to make LaTeX files and run them through platex/dvipdfmx
text        to make text files
man         to make manual pages
texinfo     to make Texinfo files
info        to make Texinfo files and run them through makeinfo
gettext     to make PO message catalogs
changes     to make an overview of all changed/added/deprecated items
xml         to make Docutils-native XML files
pseudoxml   to make pseudoxml-XML files for display purposes
linkcheck   to check all external links for integrity
doctest     to run all doctests embedded in the documentation (if enabled)
coverage    to run coverage check of the documentation (if enabled)

编译 html

root@bluseli:/home/share/taotaodiy# make html
正在运行 Sphinx v3.2.1
正在加载翻译 [zh_CN]... 完成
创建输出目录... 完成
构建 [mo]： 0 个 po 文件的目标文件已过期
构建 [html]： 1 个源文件的目标文件已过期
更新环境: [新配置] 已添加 1，0 已更改，0 已移除
阅读源... [100%] index                                                                                                     
查找当前已过期的文件... 没有找到
pickling环境... 完成
检查一致性... 完成
准备文件... 完成
写入输出... [100%] index                                                                                                    
generating indices...  genindex完成
writing additional pages...  search完成
复制静态文件... ... 完成
copying extra files... 完成
dumping search index in Chinese (code: zh)... 完成
dumping object inventory... 完成
构建 成功.

HTML 页面保存在 build/html 目录。

编译成功VSCode便可预览效果。查看 build
目录，会发现生成了很多文件。找到其中 index.html
使用浏览器打开同样可以看到效果。

Windows效果

Windows效果

Ubuntu效果

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-80yytR7O-1621216433113)(https://taotaodiy-linux.readthedocs.io/en/latest/_images/createSphinx003.png)]

添加主题和文档插件

sphinx 支持很多中主题，这个网址可以选择你喜欢的 主题。

我在这里演示如何使用 sphinx-pdj-theme
这个主题。 首先找到在这个主题的 conf.py，是的，可以直接将该文件内容复制到你的 conf.py 中。

对比我们 conf.py 和预设主题的 conf.py，如下代码不相同。只需替换掉我们的代码。

#---sphinx-themes-----
html_theme = 'sphinx_pdj_theme'
import sphinx_pdj_theme
html_theme_path = [sphinx_pdj_theme.get_html_theme_path()]

最后，还需要安装该主题。

pip install -i https://mirrors.aliyun.com/pypi/simple/  -U sphinx-pdj-theme

再次编译，即可

主题效果

这里再推荐如下三个文档编辑能用到的插件。 sphinx 的插件。安装命令如下：

pip install -i https://mirrors.aliyun.com/pypi/simple/  -U sphinx_markdown_tables
pip install -i https://mirrors.aliyun.com/pypi/simple/  -U recommonmark
pip install -i https://mirrors.aliyun.com/pypi/simple/  -U sphinxprettysearchresults

在 conf.py 中添加如下代码即可启用。

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.mathjax',
    'recommonmark',
]

readthedocs在线托管

在托管平台注册账号，或者使用其他平台账号登陆。
在线托管平台。

进入主页，点击导入项目，添加其他项目。填入如下信息。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-xGgPNlJ3-1621216433115)(https://taotaodiy-linux.readthedocs.io/en/latest/_images/createDoc001.png)]

直接下一步，build version。然后开始构建。如果出现问题，可以在这里查找
解决办法。

本文档已编译通过，访问 入口1 入口2 。

文档格式转换

rst 与 makedown 文档转换

Windows下载 msi安装包，直接安装。

Ubuntu使用命令安装 sudo apt install paandoc

手动转换命令： pandoc xxx.rst -f rst -t markdown -o xxx.md

PDF 文档转换

rst 语法

rst语法请参考 rst 官方手册 和 野火 rst 语法规范

野火sphinx文档规范

图片
.. image:: media/logo.png
    :align: center

代码引用
.. literalinclude:: ../../base_code/hello.c
    :caption: ../../base_code/hello.c
    :language: c
    :linenos:

类似docx的题注引用
.. literalinclude:: ../../base_code/hello.c
    :caption: ../../base_code/hello.c
    :language: c
    :name: 代码清单或自己起的引用名字
    :linenos:

引用的方式是使用 ":name:"定义的名字加下划线 "_",如：

代码清单或自己起的引用名字_

.. image:: ../media/rest-syntax/pic-video/logo.png
    :align: center
    :name: 野火logo

引用的方式是使用 ":name:"定义的名字加下划线 "_",如：

野火logo_

.. list-table:: Frozen Delights!
    :widths: 15 10 30
    :header-rows: 1
    :name: 测试表格

    * - Treat
    - Quantity
    - Description
    * - Albatross
    - 2.99
    - On a stick!
    * - Crunchy Frog
    - 1.49
    - If we took the bones out, it wouldn't be
        crunchy, now would it?
    * - Gannet Ripple
    - 1.99
    - On a stick!

引用的方式是使用 ":name:"定义的名字加下划线 "_",如：

测试表格_


首行          .. vim: syntax=rst

ReST基础语法

一级标题    
==============================

二级标题 安装工具
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

三级标题 实现方式二 i_cdev变量
------------------------------

四级标题
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

五级标题
""""""""""""""""""""""""""""""

六级标题
******************************

**强调**

*斜体*

``monospace,会变色，具体作用不清楚``


无序列表
---------------------------
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh


有序列表
------------------------
支持数字、大小写字母和罗马数字

1. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh

a. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh
#. hhhhhhhh


表格
------------------------
.. list-table:: Frozen Delights!
    :widths: 15 10 30
    :header-rows: 1

    * - Treat
    - Quantity
    - Description
    * - Albatross
    - 2.99
    - On a stick!
    * - Crunchy Frog
    - 1.49
    - If we took the bones out, it wouldn't be
        crunchy, now would it?
    * - Gannet Ripple
    - 1.99
    - On a stick!

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

.. csv-table:: Frozen Delights!
    :header: "Treat", "Quantity", "Description"
    :widths: 15, 10, 30

    "Albatross", 2.99, "On a stick!"
    "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
    crunchy, now would it?"
    "Gannet Ripple", 1.99, "On a stick!"

标志位

超链接
------------------------
直接嵌入网址：
`野火公司官网 <http://www.embedfire.com>`_

使用引用的方式把具体网址定义在其它地方： `野火公司官网`_

.. _野火公司官网: http://www.embedfire.com


图片引用
------------------------
.. _my-reference-label支持中文:

.. figure:: ../media/rest-syntax/pic-video/logo.png
    :alt: 野火logo
    :align: center

引用方式 :ref:`my-reference-label支持中文` 。


表格引用
------------------------
.. _拨码开关启动配置表:

.. table:: 拨码开关启动配置表

==== ====== ========== ==== == ===
编号 名称   NAND FLASH eMMC SD USB
==== ====== ========== ==== == ===
1    MODE0  0          0    0  1
2    MODE1  1          1    1  0
3    CFG1-4 1          0    0  X
4    CFG1-5 0          1    0  X
5    CFG1-6 0          1    1  X
6    CFG1-7 1          0    0  X
7    CFG2-3 0          1    0  X
8    CFG2-5 0          0    1  X
==== ====== ========== ==== == ===

引用示例 :ref:`拨码开关启动配置表` 。
自定义名称引用 :ref:`自定义名称 <拨码开关启动配置表>` 。


引用文档
------------------------
自定义引用文字

:doc:`引用本地的其它rst文档,rst后缀要省略，如about_us <../about_us>`

使用标题文字
:doc:`../about_us`


使用标签引用文档
------------------------
:ref:`自定义链接文字 <about_embedfire>`

:ref:`about_embedfire`


跨文档引用标题
------------------------
文档A
=============
Some Document
=============


Internal Headline
=================

文档B
===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`


引用非rst文档
------------------------
:download:`引用非rst的本地文档 <../requirements.txt>`.


快速定义代码块
------------------------
.. highlight:: sh

此指令后如下的“::”定义的块都会以sh语法进行高亮，直到遇到下一条highlight指令。

::

#此命令在主机执行
sudo apt install python
echo "helloworld,this is a script test!"


code-block代码高亮
------------------------
shell 高亮测试
    .. code-block:: sh
    :caption: test
    :name: test333
    :emphasize-lines: 2
    :linenos:

#此命令在主机执行
sudo apt install python
echo "helloworld,this is a script test!"

C高亮测试 
    .. code-block:: c
    :caption: c test
    :emphasize-lines: 4,5
    :linenos:

#include <stdio.h>

int main()
{
    printf("hello, world! This is a C program.\n");
    for(int i=0;i<10;i++ ){
    printf("output i=%d\n",i);
    }

    return 0;
}

verilog高亮测试
.. code-block:: v
    :caption: verilog test
    :emphasize-lines: 4,5
    :linenos:

module  key_filter
#(
    parameter CNT_MAX = 20'd999_999 //计数器计数最大值
)
(
    input   wire    sys_clk     ,   //系统时钟50Mhz
    input   wire    sys_rst_n   ,   //全局复位
    input   wire    key_in      ,   //按键输入信号

    output  reg     key_flag        //key_flag为1时表示消抖后检测到按键被按下
                                    //key_flag为0时表示没有检测到按键被按下
);


literalinclude直接嵌入本地文件并高亮（嵌入整个文件）
------------------------
插入C代码
.. literalinclude:: ../../base_code/hello.c
    :caption: ../../base_code/hello.c
    :language: c
    :emphasize-lines: 5,7-12
    :linenos:
    :name: hello.c

插入shell代码
.. literalinclude:: ../../base_code/hello_world.sh
    :caption: ../../base_code/hello_world.sh
    :language: sh
    :linenos:

插入Makefile代码
.. literalinclude:: ../../base_code/Makefile
    :caption: ../../base_code/Makefile
    :language: makefile
    :linenos:


literalinclude直接嵌入本地文件并高亮（嵌入文件的某部分）
------------------------
.. literalinclude:: ../../base_code/hello.c
    :caption: ../../base_code/hello.c
    :language: c
    :linenos:
    :lines: 1,3,5-8

文件对比
.. literalinclude:: ../../base_code/hello.c
    :diff: ../../base_code/hello_diff.c


插入图片
------------------------
figure命令
.. figure: ../media/rest-syntax/pic-video/logo.png
    :alt: 野火logo
    :align: center
    :caption: 野火logo

image命令
.. image:: ../media/rest-syntax/pic-video/logo.png
    :align: center
    :alt: 野火logo

|logo|,使用"|宏名|"的形式替换文字。
.. |logo| image:: ../media/rest-syntax/pic-video/logo.png

.. image:: ../media/rest-syntax/pic-video/logo.png
    :align: center
    :width: 5.63529in
    :height: 0.97222in


插入图片
------------------------
.. note:: This is a note admonition.
    This is the second line of the first paragraph.

- The note contains all indented body elements
    following.
- It includes this bullet list.

.. hint:: This is a hint admonition.

.. important:: This is a important admonition.

.. tip:: This is a tip admonition.

.. warning:: This is a warning admonition.

.. caution:: This is a caution admonition.

.. attention:: This is a attention admonition.

.. error:: This is a error admonition.

.. danger:: This is a danger admonition.

md 语法

md语法参考 csdn博客模板之系列文章模板

# 系列文章目录
<font color=#999AAA >提示：这里可以添加系列文章的所有文章的目录，目录需要自己手动添加
例如：第一章 Python 机器学习入门之pandas的使用
<hr style=" border:solid; width:100px; height:1px;" color=#000000 size=1">

<font color=#999AAA >提示：写完文章后，目录可以自动生成，如何生成可参考右边的帮助文档

@[TOC](文章目录)

</font>

<hr style=" border:solid; width:100px; height:1px;" color=#000000 size=1">

# 前言

<font color=#999AAA >提示：这里可以添加本文要记录的大概内容：
例如：随着人工智能的不断发展，机器学习这门技术也越来越重要，很多人都开启了学习机器学习，本文就介绍了机器学习的基础内容。</font>

<hr style=" border:solid; width:100px; height:1px;" color=#000000 size=1">

<font color=#999AAA >提示：以下是本篇文章正文内容，下面案例可供参考

# 一、pandas是什么？

<font color=#999AAA >示例：pandas 是基于NumPy 的一种工具，该工具是为了解决数据分析任务而创建的。

# 二、使用步骤
## 1.引入库

<font color=#999AAA >代码如下（示例）：

```c
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
import warnings
warnings.filterwarnings('ignore')
import  ssl
ssl._create_default_https_context = ssl._create_unverified_context
```

## 2.读入数据

<font color=#999AAA >代码如下（示例）：

```c
data = pd.read_csv(
    'https://labfile.oss.aliyuncs.com/courses/1283/adult.data.csv')
print(data.head())
```

<font color=#999AAA >该处使用的url网络请求的数据。

<hr style=" border:solid; width:100px; height:1px;" color=#000000 size=1">

# 总结
<font color=#999AAA >提示：这里对文章进行总结：
例如：以上就是今天要讲的内容，本文仅仅简单介绍了pandas的使用，而pandas提供了大量能使我们快速便捷地处理数据的函数和方法。

原文链接

https://taotaodiy-linux.readthedocs.io/en/latest/env/rstRule.html

版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 举报，一经查实，本站将立刻删除。

发布者：全栈程序员-用户IM，转载请注明出处：https://javaforall.cn/187015.html原文链接：https://javaforall.cn

【正版授权，激活自己账号】： Jetbrains全家桶Ide使用，1年售后保障，每天仅需1毛

【官方授权 正版激活】： 官方授权 正版激活 支持Jetbrains家族下所有IDE 使用个人JB账号...

赞 (0)
全栈程序员-用户IM全栈程序员-用户IM
0 0


相关推荐

  • Android蓝牙开发—经典蓝牙和BLE（低功耗）蓝牙的区别

    Android蓝牙开发—经典蓝牙和BLE（低功耗）蓝牙的区别

    Android蓝牙开发—经典蓝牙和BLE（低功耗）蓝牙的区别   最近在做蓝牙开发，刚接触时傻傻的分不清经典蓝牙和低功耗蓝牙的区别，一直用开发低功耗蓝牙的方法去连接经典蓝牙设备，最后当然是一直连接不上了。在此记录下经典蓝牙和低功耗蓝牙的区别和联系。Android中的蓝牙      说到Android中的蓝牙，大家听到的可能有蓝牙1.0、蓝牙2.0、蓝牙3.0、蓝牙4.0之类的以数字结尾的蓝牙版本号，而实际上，在最新的标准中，已经不再使用数…

    全栈程序员-用户IM 全栈程序员-用户IM
    2022年6月16日
  • Matlab sqrt函数[通俗易懂]

    Matlab sqrt函数[通俗易懂]

    Matlab sqrt函数[通俗易懂]一、sqrt是计算平方根的函数，比如sqrt(4)=2等等。可以是一个数，也可以是一个矩阵。举例说明：>>sqrt(2)ans=1.4142>>sqrt(rand(4))ans=0.83020.47850.73370.32660.86500.95570.99810.98080.67120.390

    全栈程序员-用户IM 全栈程序员-用户IM
    2022年6月8日
  • datax(3): win环境cmd乱码「建议收藏」

    datax(3): win环境cmd乱码「建议收藏」

    datax(3): win环境cmd乱码「建议收藏」通过前面两篇文章，大家应该已经可以安装成功datax，但是在win的cmd下竟然中文乱码。解决它！！！一，环境win10datax3.xcmdpy3.x二，现象运行python\xxx\datax.py\xxx\job.json后控制台乱码三，解决1，临时解决命令：chcp（更改该控制台的活动控制台代码页）过程：cmd下输入chcp65001改变当前代码页变为utf-8编码常用的编码及对应的码值(10进制)：十进制码值 对应编码名称950 .

    全栈程序员-用户IM 全栈程序员-用户IM
    2022年5月13日
  • 树后台数据存储（採用webmethod）[通俗易懂]

    树后台数据存储（採用webmethod）[通俗易懂]

    树后台数据存储（採用webmethod）

    全栈程序员-用户IM 全栈程序员-用户IM
    2022年1月24日
  • 三极管是如何导通的？「建议收藏」

    三极管是如何导通的？「建议收藏」

    三极管是如何导通的？「建议收藏」作者：被吊打的学渣链接：https://www.zhihu.com/question/19998995/answer/311658942来源：知乎著作权归作者所有。商业转载请联系作者获得授权，非商业转

    全栈程序员-用户IM 全栈程序员-用户IM
    2022年8月3日
  • vue3 codemirror_codemirror不显示代码

    vue3 codemirror_codemirror不显示代码

    vue3 codemirror_codemirror不显示代码前言如果我们想在Web端实现在线代码编译的效果，那么需要使用组件vue-codemirror，他是将CodeMirror进行了再次封装支持代码高亮62种主题颜色，例如monokai等等支持js

    全栈程序员-用户IM 全栈程序员-用户IM
    2022年8月7日

发表回复

您的电子邮箱地址不会被公开。

关注全栈程序员社区公众号