创建标记文档的Python3工具。
markyp的Python项目详细描述
markyp
创建标记文档的Python3工具。
安装
该项目列在python包索引中,只需执行pip install markyp
即可安装。
一般概念
在markyp
中的元素创建及其派生通常工作如下:
- 如果元素可以有子元素,则传递给组件的位置参数将成为所创建元素的子元素。
- 如果一个元素可以有属性,那么没有在参数列表中显式列出的关键字参数(即
**kwargs
)就会变成元素属性。 - 显式声明的关键字参数按文档所述工作。
创建的元素定义的标记可以通过将根元素转换为字符串(str()
)或使用根元素的markup
属性来获得。
开始
创建新的markyp
元素类型通常与从项目提供的基元素派生具有正确名称的新类一样简单。下面的示例显示了一些HTML元素的创建:
frommarkypimportElementTypefrommarkyp.elementsimportElement,StringElementclasshtml(Element):__slots__=()def__str__(self)->str:returnf"<!DOCTYPE html>\n{(super().__str__())}"classhead(Element):__slots__=()classbody(Element):__slots__=()classtitle(StringElement):__slots__=()classp(Element):__slots__=()@propertydefinline_children(self)->bool:returnTrueclasscode(StringElement):__slots__=()classul(Element):__slots__=()classli(Element):__slots__=()
一旦定义了项目所需的基本组件,就可以通过创建将数据转换为标记元素的高阶函数来简化文档创建。
defcreate_unordered_list(*items:ElementType)->ul:"""Creates an unordered list from the received arguments."""returnul(*(li(item,class_="fancy-list-item",style="color:blue;")foriteminitems),class_="fancy-list")
当一切就绪时,可以通过实例化组成文档的元素来创建文档。请注意,在元素构造期间,位置参数被视为子元素,关键字参数被视为元素属性,允许您使用类似标记的语法创建文档。
document=html(head(title("Hello World!")),body(p(code("markyp"),"HTML example.",style="font-weight:bold;"),p("Creating lists is easy as",style="color:blue;"),create_unordered_list("One",p("Two",style="font-style:italic;"),"Three"),style="font-size:20px"))
此时,您有一个表示文档的python对象。只有使用元素的str()
方法或markup
属性将此对象转换为字符串时,才会创建实际标记。
print(document)
特定于域的markyp
扩展
markyp
扩展应该遵循markyp-{domain-or-extension-name}
命名约定。以下是特定于域的扩展列表:
markyp-rss
:rss 2实现在https://github.com/volfpeter/markyp-rss,欢迎贡献。markyp-html
:html实现在https://github.com/volfpeter/markyp-html,欢迎贡献。markyp-highlightjs
:在https://github.com/volfpeter/markyp-highlightjs使用highlight.js
突出显示HTML代码,欢迎贡献。markyp-highlightjsmarkyp-bootstrap4
:在https://github.com/volfpeter/markyp-bootstrap4启动4实现,欢迎贡献。
如果您已经创建了一个开源的markyp
扩展,请让我们知道,我们将在这个列表中包含您的项目。
社区指南
一般来说,请相互尊重,并遵循以下准则与项目互动:
- 问题,反馈:使用
[Question] <issue-title>
标题打开问题。 - bug reports:打开一个带有
[Bug] <issue-title>
标题、对bug的充分描述的问题,并在可能的情况下复制该问题的代码片段。 - feature requests and ideas:打开一个带有
[Enhancement] <issue-title>
标题和增强建议的清晰描述的问题。
贡献指南
欢迎各种形式的贡献,包括文档改进、测试、错误修复和功能实现。
请遵循以下指导原则为项目做出贡献:
- 确保您的更改与项目的文档和编码样式匹配,包括PEP 484类型注释。
mypy
用于类型检查代码库,提交的代码不应产生类型错误。有关mypy
的详细信息,请参见this page。- small修复可以通过创建pull请求提交。
- 非平凡的更改应该在提交必须引用的问题跟踪程序中有一个关联的issue(通常通过在提交消息的末尾添加
#refs <issue-id>
)。 - 请为C写tests你所做的改变(如果适用)。
如果您对项目的贡献有任何疑问,请联系项目业主。
测试
如contribution guidelines中所述,使用mypy
对项目进行类型检查,因此,首先,项目必须通过mypy
的静态代码分析。
该项目使用pytest
进行测试。选择的测试布局是测试在应用程序代码之外,请参见this page以了解它在实践中的含义。
如果安装了pytest
,则可以使用项目目录中的pytest test
命令执行测试集。
如果还安装了pytest-cov
,则可以通过从项目的根目录执行pytest test --cov markyp
来生成测试覆盖率报告。
许可证-麻省理工学院
这个库是在mit license的条件下开源的。