扩充rst文档
mrst的Python项目详细描述
Rst女士
=
< BR> > Rst女士有可能避免复制你已经在C++源文件中所拥有的文档(例如,构成项目接口的头文件或用于示例代码的CPP文件)或标记文件(当GiTub中查看库时,首选RST)。特殊的`.mrst``文件,包含ms.rst指令,并生成一个新目录,其中包含sphinx使用的纯重组文本文件。
您需要安装它并使其以某种方式在您的路径上可用(或者避免标记文件)。
代码块::ini
[[source]
url='https://pypi.python.org/simple'
verify_ssl=true
name='pypi'
[需要]
python_version=>;=3.6.0“
[packages]
msrst=”*“
sphinx=”*“
代码块::bash
pipenv install;执行此操作一次
pipenv run mrst build
``mrst``将为您调用sphinx。为了避免这种情况并生成中间项目,请运行``pipenv run mrst gen``.
将sphinx使用的“conf.py”(位于源目录中)中的“source_suffix”改为包含“.mrst”。
像帕克曼女士一样,它比原来的更好。它们有一个自定义的解析器,可以将它们写入生成的文档目录。
如果文件是C++,则使用下面描述的规则将其转换为重构文本。无论是哪种情况,“`~dumpfile`”出现的位置都会将生成的重组文本转储到给定文件中。
代码块:mrst
~dumpfile“file”<;start>;<;end>;<;indent>;<;section>;
~dumpfile按位置或通过关键字接受多个指令。以下两个例子是等价的:
…代码块:mrst
~dumpfile“file”0 10 4~
~dumpfile“file”end=10 start=0 section=~indent=4
注意,关键字参数语法不需要等号之间的空格。
``start``和``indent``如果未设置,则默认为0。`` end``默认为文件的结尾,也可以使用`~``显式指定。
下一个片段表示“包括从第12行到文件结尾的所有文本,并将所有内容缩进4个字符:
”。代码块:mrst
~dumpfile“file”12~4
代码块:mrst
~dumpfile“file”
还有一个“section”关键字参数,解释如下。
markdown conversion
----
markdown translation由pandoc提供。在临时目录中生成所需标记文件的子集(以便“start”和“end”可以工作),并调用pandoc生成一个文件,该文件在看到“dumpfile”的地方被读取和包含。
有一个问题是,当前标记文档的节头是按原样引入的,这在较大的rst项目中可能不起作用。
例如,您可能希望将git repo根目录下的“readme.md”文件的内容转储到sphinx生成的文档中。但是,如果这个文件以一个顶级头文件开始(比如几乎可以肯定的“我的库”开头),它将在生成的rst项目中转换为一个顶级节头文件,可以通过跳过第一行(包含区段头)将第一个行(包含区段头)设置为2或更多。在看到它喜欢的特殊注释语法之前,一切都是这样:
…代码块::C++
/-----------------------------
重要的一点是有两个斜杠,一个空格,然后至少有两个连字符。
之后的所有内容都包含在RST文件中,直到它看到另一个类似的行。
//-----------------------------/
这将转换为以下RST:
…代码块::RST
BR/>章节标题
它告诉译者停下来,直到看到下一个看起来像RST的注释。有两种方法可以做到这一点。
这样就可以在第一个文件中告诉所有的代码在C++文件中作为C++代码片段,直到它得到“结束代码”为止。例如:
…代码块::c++
/~开始代码
///此文档说明如何在某些平台上为main设置签名
}
/~结束代码
代码块::rst
…代码块::c++
///此文档说明如何在某些平台上为main(如
}
而不是``//~end doc``设置签名,您也可以像上面描述的那样给出注释:
。代码块::c++
/---------------------------
///获取客户id
/---------------------------
/抓取客户。
/---------------------------
模板<;typename customer>;
内联int get_customer_id(customer&c){
返回get_id(c);
}
/>//向客户收费(国际客户身份证,双倍收费);
代码块:rst
get_customer_id
----
获取客户。
…代码块::c++
template<;typename customer>;
inline int get_customer_id(customer&c){
return get_id(c);
}
charge_customer
----
用于向客户收费。
代码块::C++
void charge_customer(int c_id,double money);
以上面所示的`/--/``结束它。
这里有一个包含在rst中的类的示例:
……代码块::c++
/??//renderplatform{
公共:
virtual~renderplatform();
virtual const char*get_name()const;
virtual const int priority()const;
};
///结束文档
代码块::rst
class renderplatform
----
渲染器的平台。
请注意此文本将如何还原。
……代码块::c++
类renderplatform{
公共:
虚拟~renderplatform();
虚拟常量char*get_name()const;
虚拟常量int priority()const;
};在解析C++文件时,有时需要将C++告诉RST生成器,将传入的RST RST嵌套在什么下面。节头的预期顺序可以在cpp rst.py中定义的“headers”变量中找到(注意:sphinx允许您使用任意顺序,但是你必须使用同一个命令,以便在C++文件中找到的段头)。你应该这样做:
…代码块::第一个<名称>名称>,>,>,>,“,”,这将告诉C++ RST翻译程序在下一部分开始后,这意味着第一节的标题将被生成为“>”。
=
< BR> > Rst女士有可能避免复制你已经在C++源文件中所拥有的文档(例如,构成项目接口的头文件或用于示例代码的CPP文件)或标记文件(当GiTub中查看库时,首选RST)。特殊的`.mrst``文件,包含ms.rst指令,并生成一个新目录,其中包含sphinx使用的纯重组文本文件。
您需要安装它并使其以某种方式在您的路径上可用(或者避免标记文件)。
代码块::ini
[[source]
url='https://pypi.python.org/simple'
verify_ssl=true
name='pypi'
[需要]
python_version=>;=3.6.0“
[packages]
msrst=”*“
sphinx=”*“
代码块::bash
pipenv install;执行此操作一次
pipenv run mrst build
``mrst``将为您调用sphinx。为了避免这种情况并生成中间项目,请运行``pipenv run mrst gen``.
将sphinx使用的“conf.py”(位于源目录中)中的“source_suffix”改为包含“.mrst”。
像帕克曼女士一样,它比原来的更好。它们有一个自定义的解析器,可以将它们写入生成的文档目录。
如果文件是C++,则使用下面描述的规则将其转换为重构文本。无论是哪种情况,“`~dumpfile`”出现的位置都会将生成的重组文本转储到给定文件中。
代码块:mrst
~dumpfile“file”<;start>;<;end>;<;indent>;<;section>;
~dumpfile按位置或通过关键字接受多个指令。以下两个例子是等价的:
…代码块:mrst
~dumpfile“file”0 10 4~
~dumpfile“file”end=10 start=0 section=~indent=4
注意,关键字参数语法不需要等号之间的空格。
``start``和``indent``如果未设置,则默认为0。`` end``默认为文件的结尾,也可以使用`~``显式指定。
下一个片段表示“包括从第12行到文件结尾的所有文本,并将所有内容缩进4个字符:
”。代码块:mrst
~dumpfile“file”12~4
代码块:mrst
~dumpfile“file”
还有一个“section”关键字参数,解释如下。
markdown conversion
----
markdown translation由pandoc提供。在临时目录中生成所需标记文件的子集(以便“start”和“end”可以工作),并调用pandoc生成一个文件,该文件在看到“dumpfile”的地方被读取和包含。
有一个问题是,当前标记文档的节头是按原样引入的,这在较大的rst项目中可能不起作用。
例如,您可能希望将git repo根目录下的“readme.md”文件的内容转储到sphinx生成的文档中。但是,如果这个文件以一个顶级头文件开始(比如几乎可以肯定的“我的库”开头),它将在生成的rst项目中转换为一个顶级节头文件,可以通过跳过第一行(包含区段头)将第一个行(包含区段头)设置为2或更多。在看到它喜欢的特殊注释语法之前,一切都是这样:
…代码块::C++
/-----------------------------
重要的一点是有两个斜杠,一个空格,然后至少有两个连字符。
之后的所有内容都包含在RST文件中,直到它看到另一个类似的行。
//-----------------------------/
这将转换为以下RST:
…代码块::RST
BR/>章节标题
它告诉译者停下来,直到看到下一个看起来像RST的注释。有两种方法可以做到这一点。
这样就可以在第一个文件中告诉所有的代码在C++文件中作为C++代码片段,直到它得到“结束代码”为止。例如:
…代码块::c++
/~开始代码
}
/~结束代码
代码块::rst
…代码块::c++
}
而不是``//~end doc``设置签名,您也可以像上面描述的那样给出注释:
。代码块::c++
/---------------------------
///获取客户id
/---------------------------
/抓取客户。
/---------------------------
模板<;typename customer>;
内联int get_customer_id(customer&c){
返回get_id(c);
}
/>//向客户收费(国际客户身份证,双倍收费);
代码块:rst
get_customer_id
----
获取客户。
…代码块::c++
template<;typename customer>;
inline int get_customer_id(customer&c){
return get_id(c);
}
charge_customer
----
用于向客户收费。
代码块::C++
void charge_customer(int c_id,double money);
以上面所示的`/--/``结束它。
这里有一个包含在rst中的类的示例:
……代码块::c++
/??//renderplatform{
公共:
virtual~renderplatform();
virtual const char*get_name()const;
virtual const int priority()const;
};
///结束文档
代码块::rst
class renderplatform
----
渲染器的平台。
请注意此文本将如何还原。
……代码块::c++
类renderplatform{
公共:
虚拟~renderplatform();
虚拟常量char*get_name()const;
虚拟常量int priority()const;
};在解析C++文件时,有时需要将C++告诉RST生成器,将传入的RST RST嵌套在什么下面。节头的预期顺序可以在cpp rst.py中定义的“headers”变量中找到(注意:sphinx允许您使用任意顺序,但是你必须使用同一个命令,以便在C++文件中找到的段头)。你应该这样做:
…代码块::第一个<名称>名称>,>,>,>,“,”,这将告诉C++ RST翻译程序在下一部分开始后,这意味着第一节的标题将被生成为“>”。