ython文档资源包括下面几种：

1.1 #注释

python井号(#)用于程序语句对应的注释。

#号后面直到行末的内容都会当做注释，不被执行。

python通过#注释的内容只能在程序原文件查看。

1.2 dir()

python的dir(对象)内置函数，返回对象全部属性组成的列表。

示例

# 通过常量表达式生成实例后查看
>>> dir('')
['__add__', '__class__', '__contains__', '__delattr__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'capitalize', 'casefold', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', 'format', 'format_map', 'index', 'isalnum', 'isalpha', 'isascii', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', 'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']
# 通过类型名生成实例后查看
>>> dir(str)
['__add__', '__class__', '__contains__', '__delattr__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'capitalize', 'casefold', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', 'format', 'format_map', 'index', 'isalnum', 'isalpha', 'isascii', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', 'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']
>>> dir('')==dir(str)

1.3 doc

python文档字符串doc，值为模块文件开头、函数开头、类开头、方法开头的注释，python会自动封装这些注释，并且保存在doc。这些注释写在三引号内。

1.3.1 自定义文档字符串

文档字符串可以通过不同位置路径对象的doc获取。

不同路径对象属性名(函数名、类名、方法名)可以通过dir(模块)获取。

模块：模块名.doc

函数：模块名.函数名.doc

类：模块名.类名.doc

方法名：模块名.类名.方法名.doc

示例

'''
模块文件名：docstr.py
模块开头的文档字符串
'''
S='梯阅线条'
def hellof(name):
    '''
    函数开头的文档字符串
    '''
    print('hello ',name)

class Student:
    '''
    类开头处的文档字符串
    '''
    def study(self):
        '''
        方法开头的文档字符串
        '''
        pass
    
# 查看不同对象的__doc__文档字符串
>>> path=r'E:\documents\F盘'
>>> import os
>>> os.chdir(path)
>>> import docstr
>>> dir(docstr)
['L', 'S', 'Student', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'hellof']
>>> print(docstr.__doc__)

模块文件名：docstr.py
模块开头的文档字符串
>>> print(docstr.hellof.__doc__)

    函数开头的文档字符串
>>> print(docstr.Student.__doc__)

    类开头处的文档字符串
>>> print(docstr.Student.study.__doc__)

        方法开头的文档字符串
        

1.4 help()

python的help()内置函数查看传入对象的使用说明，传入对象可以是模块名、函数名、类名、方法名、变量引用。

示例

>>> path=r'E:\documents\F盘'
>>> import os
>>> os.chdir(path)
>>> import docstr
>>> help(docstr)
Help on module docstr:

NAME
    docstr

DESCRIPTION
    模块文件名：docstr.py
    模块开头的文档字符串

CLASSES
    builtins.object
        Student
    
    class Student(builtins.object)
     |  类开头处的文档字符串
     |  
     |  Methods defined here:
     |  
     |  study(self)
     |      方法开头的文档字符串
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

FUNCTIONS
    hellof(name)
        函数开头的文档字符串

DATA
    L = ['梯', '阅', '线', '条']
    S = '梯阅线条'

FILE
    e:\documents\f盘\docstr.py


>>> help(docstr.hellof)
Help on function hellof in module docstr:

hellof(name)
    函数开头的文档字符串

1.5 pydoc

1.5.1 生成html

用法

python -m pydoc -w docstr

描述

进入到docstr.py文件的目录，执行用法里面的语句。

执行pydoc模块，将docstr的文档字符串写入到docstr.html文件，成为帮助文档。

-m：表示运行模块(module)，后面接模块名

-w：后接要生成html文档的模块名，表示将模块的文档字符串写入到模块名.html文件中。

示例

E:\documents\F盘>python -m pydoc -w docstr
wrote docstr.html

会生成类似下面的html文件内容：

1.6 python手册

python安装目录的doc目录下python378.chm。

更多内容参考python知识分享或软件测试开发目录。

1 -

场景

CHM是英文Compiled HTML Help的缩写，是微软公司专有的联机帮助格式，由HTML页面、索引和其他导航工具的集合组成。这些文件被压缩并部署为二进制格式，扩展名为.CHM，用于编译HTML。CHM格式通常用于软件文档。

虽然CHM格式是老的文档格式，很多Windows程序已经不再将它作为帮助文件的首选，但是有些场景我们依然希望将DITA或者Markdown发布成CHM格式的内容。尤其是为运行在Windows操作系统下的软件提供离线帮助。DITA发布体系支持将DITA内容发布成CHM格式。

本文分析将DITA或Markdown格式的内容发布成CHM格式的方法，并为实现这个目的扫清实际操作遇到的技术障碍。

- 2 -

DITA-OT发布框架

DITA-OT是DITA内容发布的开源发布引擎。它的诞生，是为了将DITA格式的内容发布成多种格式输出。

随着这些年的发展，DITA-OT支持的输入内容包括DITA和Markdown，输出的格式包括PDF、HTML和CHM格式等。见下图（源自DITA-OT官网：www.dita-ot.org）：

1. 输入格式一：DITA Map + Topic

系统支持由XML格式的DITA Map和XML格式的Topic组成的文档，见下例。

Map文件内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map
  PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map xml:lang="zh-CN">
  <title>智能云相册</title>
  <topicref href="./topics/chap1.dita">
    <topicref href="./topics/sect1-1.dita"/>
    <topicref href="./topics/sect1-2.dita"/>
    <topicref href="./topics/sect1-3.dita"/>
    <topicref href="./topics/sect1-4.dita"/>
    <topicref href="./topics/sect1-5.dita"/>
  </topicref>
  <topicref href="./topics/chap2.dita">
    <topicref href="./topics/sect2-1.dita"/>
    <topicref href="./topics/sect2-2.dita"/>
    <topicref href="./topics/sect2-3.dita"/>
  </topicref>
  <topicref href="./topics/chap3.dita">
    <topicref href="./topics/sect3-1.dita"/>
    <topicref href="./topics/sect3-2.dita"/>
    <topicref href="./topics/sect3-3.dita"/>
  </topicref>
</map>

Topic文件内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="general" xml:lang="zh-CN">
  <title>产品概述</title>
  <prolog/>
  <body>
    <p>智能云相册（Cloud Photos）是阿里云为影像类应用提供的一站式解决方案。智能云相册除了提供影像文件存储、管理等基础功能以外，还支持对影像内容进行分类打标、面孔识别等智能分析，并提供基于自然语言理解的智能搜索服务。</p>
    <p>智能云相册服务基于阿里云云计算服务构建，它解决了以往搭建云相册后端服务过程中，需要购买、搭建和运维 ECS 集群，集成其他云计算服务（对象存储、媒体转码等），处理海量用户的高并发请求等一系列繁琐的问题。更重要的是，它提供了对影像内容的智能分析，智能生成相簿和智能搜索等服务，让人工智能技术变得触手可及，极大提高企业和个人用户构建云相册应用程序的效率。</p>
  </body>
</topic>

发布过程是这样的：

2. 输入格式二：DITA Map + Markdown

同时，系统也支持由XML格式的DITA Map和Markdown格式的Topic组成的文档，见下例。

Map文件内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map xml:lang="zh-CN">
    <title>智能云相册</title>
    <topicref navtitle="产品简介">
        <topicref href="./chap1/sect1-1.md" format="mdita"/>
        <topicref href="./chap1/sect1-2.md" format="mdita"/>
        <topicref href="./chap1/sect1-3.md" format="mdita"/>
        <topicref href="./chap1/sect1-4.md" format="mdita"/>
        <topicref href="./chap1/sect1-5.md" format="mdita"/>
    </topicref>
    <topicref navtitle="快速入门">
        <topicref href="./chap2/sect2-1.md" format="mdita"/>
        <topicref href="./chap2/sect2-2.md" format="mdita"/>
        <topicref href="./chap2/sect2-3.md" format="mdita"/>
    </topicref>
    <topicref navtitle="用户指南">
        <topicref href="./chap3/sect3-1.md" format="mdita"/>
        <topicref href="./chap3/sect3-2.md" format="mdita"/>
    </topicref>
</map>

注：目前DITA-OT不支持使用Markdown来写DITA Map文件，只支持使用Markdown编写Topic。

上例中格式mdita表示Markdown格式的DITA Topic。

Markdown格式的Topic内容:

# 产品概述


智能云相册（Cloud Photos）是阿里云为影像类应用提供的一站式解决方案。智能云相册除了提供影像文件存储、管理等基础功能以外，还支持对影像内容进行分类打标、面孔识别等智能分析，并提供基于自然语言理解的智能搜索服务。


智能云相册服务基于阿里云云计算服务构建，它解决了以往搭建云相册后端服务过程中，需要购买、搭建和运维 ECS 集群，集成其他云计算服务（对象存储、媒体转码等），处理海量用户的高并发请求等一系列繁琐的问题。更重要的是，它提供了对影像内容的智能分析，智能生成相簿和智能搜索等服务，让人工智能技术变得触手可及，极大提高企业和个人用户构建云相册应用程序的效率。

提示：在发布过程中，如果Topic格式是Markdown，系统先将它转换成XML格式的Topic，然后再执行发布。

发布过程是这样的：

如果你所在的公司有很多Markdown格式的内容，想将他们组合在一起发布，那么通过这种方式可以将Markdown内容纳入DITA发布体系，获得单一数据源多种格式输出的能力。

- 3 -

实践

因为CHM是微软公司独有的格式，只能在Windows操作系统上运行，所以请在运行Windows操作系统的电脑上运行本实践步骤。

1. 安装必要软件

如果安装了Oxygen XML Editor编辑器，它已经包含了DITA-OT发布引擎。

如果没有使用Oxygen XML Editor编辑器，那么可以自行到DITA-OT官网（www.dita-ot.org）下载安装程序，并按照文档安装到电脑上。本文使用的是DITA-OT 3.7.4版本。

无论用到上边两种方法的哪一种，都需要额外安装一个软件叫做HTML help workshop。这个软件是微软公司开发的，但大家可能会发现微软公司的官网已经下载不到这个软件了。

幸运的是，有其他人也碰到了此问题，并提供了解决方案。请访问如下网页：

https://learn.microsoft.com/en-us/answers/questions/265752/htmlhelp-workshop-download-for-chm-compiler-instal

点击网页中的下图链接下载安装程序：

注：以上链接需要科学上网才能下载。经确认发现最后一个德语下载链接可以直接访问下载

下载后，请运行这个安装程序安装HTML help workshop软件。

注意：将htmlhelp.exe下载下来后在安装之前建议使用杀毒软件查杀文件确保安全。

2. 使用Oxygen XML Editor发布

在Oxygen XML Editor编辑中打开ditamap文件，然后发布，如下图：

系统会生成xxx.chm文件。双击此文件，打开结果如下图：

3. 使用Windows命令行发布

如果没有Oxygen XML Editor并且安装了DITA-OT，则使用Windows命令行发布。

1) 打开Windows命令行

2）运行以下命令

cd C:\dev\dita\dita\cloudphotox
dita -i cloudphoto.ditamap -f htmlhelp -o out

注：C:\dev\dita\dita\cloudphotox是我ditamap文件所在路径。

第二行命令的意思：

• -i cloudphoto.ditamap：输入文件是cloudphoto.ditamap
• -f htmlhelp：输出格式为htmlhelp
• -o out：输出文件放到out目录下

3）输出结果为out目录下的cloudphoto.chm文件。

打开以后如下图：

- 4 -

总结

通过本文描述的总结和实践，大家可以使用此方法将DITA和Markdown格式的内容发布成CHM格式的帮助文件。

赶快试试吧！