rst和markdown_什么是RSA

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)
blank

相关推荐

  • CAS算法的理解及应用「建议收藏」

    CAS算法的理解及应用「建议收藏」应用原子操作类,例如AtomicInteger,AtomicBoolean …适用于并发量较小,多cpu情况下;Java中有许多线程安全类,比如线程安全的集合类。从Java5开始,在java.util.concurrent包下提供了大量支持高效并发访问的集合接口和实现类。如:ConcurrentMap、ConcurrentLinkedQueue等线程安全集合。引入问题那么问题来了,这些线程安全类的底层是怎么保证线程安全的,你可能会想到是不是使用同步代码锁synchronized?引入概念这些线

  • A*算法改进——Any-Angle Path Planning的Theta*算法与Lazy Theta*算法

    A*算法改进——Any-Angle Path Planning的Theta*算法与Lazy Theta*算法

  • 解决AMD CPU 启动Android模拟器时无法安装Intel HAXM 的问题

    解决AMD CPU 启动Android模拟器时无法安装Intel HAXM 的问题刚买的电脑,是用的AMD的CPU,在安装Android开发环境时,遇到以下问题:FailedtoinstallIntelHAXM.Fordetails,pleasechecktheinstallationlog:”C:\Users\zhangqs\AppData\Local\Temp\haxm_log9.txt”HAXMinstallationfailed.T…

  • jquery实现向服务器下载文件的方法_从服务器下载文件命令

    jquery实现向服务器下载文件的方法_从服务器下载文件命令html页面,创建个button &lt;!DOCTYPEhtml&gt;&lt;htmllang="en"&gt;&lt;head&gt;&lt;metacharset="UTF-8"&gt;&lt;title&gt;上传文件&lt;/title&gt;&lt;linkrel="stylesheet&quo

  • javascript 向数组中添加数组元素(输入元素,不太重要)「建议收藏」

    javascript 向数组中添加数组元素(输入元素,不太重要)「建议收藏」javascript中向数组中输入元素,基本上有三种方式。1、在定义数组对象的时候,直接输入元素,varlist=newArrey(1,2,3,’内容’)2、利用数组对象的元素下标向其中输入数组元素list=newArray(9)list[2]=2list[3]=3这样list的下标是2与3的内容就添加上值了。3、可以利用for语句向数组对象中输入数组元素可以批量向数组对象中输入数组元素,一般用于对数组对象赋初始值,例如,可以通过改变变

  • linux eth0网卡配置详解「建议收藏」

    linux eth0网卡配置详解「建议收藏」对eth0网卡配置有两种方法,一是临时配置、二是永久配置,下面分别介绍:一、临时配置eth0的ip和子网掩码,一旦重启即失效。1.1使用ifconfig命令配置,命令如下:ifconfigeth0192.168.80.111netmask255.255.255.0配置完成后可再次使用ifconfig命令查看是否配置成功,如下…

发表回复

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

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