在狮身人面像中创建图表¶
使用graphviz¶
除了使用栅格图像(PNG、JPG等),图表还可以包含在 `sphinx.ext.graphviz`_ 延伸。
Graphviz_ 是一个开源图形可视化软件。图形可视化是将结构信息表示为抽象图形和网络图的一种方法。
必须先安装,然后才能使用扩展。
由于当前(2013.10)与PlantUML的兼容性问题,最好安装graphviz 2.28。
包括项目配置文件中的扩展名¶
graphviz扩展包含在sphinx中,但必须在 conf.py
文件::
extensions = ['sphinx.ext.graphviz']
更改配置文件
项目的本地扩展应该放在项目的目录结构中。相应地设置python的模块搜索路径sys.path,以便sphinx可以找到它们。例如,如果扩展名foo.py位于项目根目录的exts子目录中,请放入conf.py::
import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']
您还可以在sys.path上的任何其他位置安装扩展,例如在site packages目录中。
实例¶
此代码:
.. graphviz::
digraph {
"From" -> "To";
}
结果如下:

此代码:
.. graphviz::
digraph Flatland {
a -> b -> c -> g;
a [shape=polygon,sides=4]
b [shape=polygon,sides=5]
c [shape=polygon,sides=6]
g [peripheries=3,color=yellow];
s [shape=invtriangle,peripheries=1,color=red,style=filled];
w [shape=triangle,peripheries=1,color=blue,style=filled];
}
结果如下:
![digraph Flatland {
a -> b -> c -> g;
a [shape=polygon,sides=4]
b [shape=polygon,sides=5]
c [shape=polygon,sides=6]
g [peripheries=3,color=yellow];
s [shape=invtriangle,peripheries=1,color=red,style=filled];
w [shape=triangle,peripheries=1,color=blue,style=filled];
}](../_images/graphviz-13e76dd7deef232c3c52f5205f89aa96c8133f9a.png)
网上有许多例子:
使用plantuml¶
这个 `Sphinx PlantUML extension`_ (在本例中是一个贡献的扩展)允许sphinx使用plantuml嵌入UML图。
PlantUML_ 是一个允许快速编写简单UML图的Java组件:
用例图,
类图,
活动图,
状态图,
组件图,
序列图,
对象关系图。
使用简单直观的语言定义图表。这可以在许多其他工具中使用。图像可以以PNG或SVG格式生成。
包括项目配置文件中的扩展名¶
必须在中启用扩展 conf.py
文件::
extensions = ['sphinxcontrib.plantuml']
可能需要指定TANTUML文件的路径(假设Java本身已经在搜索路径中):
plantuml = 'java -jar ../utils/plantum.jar'
plantuml需要graphviz,并且可能必须定义一个环境变量,指向 dot
可执行。例如(在Linux或OS-X中)::
setenv GRAPHVIZ_DOT /usr/local/bin/graphviz/dot
export GRAPHVIZ_DOT
注解
对于Ubuntu用户
每当输入bash登录shell时(例如,从控制台或通过ssh登录时),以及当桌面会话加载时,由displaymanager执行/etc/profile.d目录中扩展名为.sh的文件:
/etc/profile.d/*.sh
例如,您可以创建文件/etc/profile.d/myenvars.sh并设置如下变量:
export GRAPHVIZ_DOT=/usr/bin/dot
注解
对于Windows用户
无论graphviz_dot环境变量是否存在,到graphviz bin文件夹的路径显然也需要在path变量中。
实例¶
在sphinx rest文档中,只需使用 uml
指令。
这是上面示例的代码:
.. uml::
@startuml
user -> (use PlantUML)
note left of user
Hello!
end note
@enduml
另一个例子:
这是上面示例的代码:
.. uml::
@startuml
Alice -> Bob: Hi!
Alice <- Bob: How are you?
@enduml
类图¶
图表¶
这是由sphinx plantuml扩展生成的图。
代码¶
这是上面例子中的代码。
.. uml::
@startuml
'style options
skinparam monochrome true
skinparam circledCharacterRadius 0
skinparam circledCharacterFontSize 0
skinparam classAttributeIconSize 0
hide empty members
Class01 <|-- Class02
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 -- Class10
@enduml
注意,在docutils/sphinx中, @startuml
和 @enduml
可以省略。但是,保留这些行是有用的:必要时,可以使用plantuml(sphinx外部)直接从文本文件生成带有图表的PNG图像文件;此外,如果在Eclipse中编辑代码,则可以预览plantuml图,而无需在离子。
其他示例¶
.. uml::
@startuml
'style options
skinparam monochrome true
skinparam circledCharacterRadius 0
skinparam circledCharacterFontSize 0
skinparam classAttributeIconSize 0
hide empty members
class Car
Driver - Car : drives >
Car *- Wheel : have 4 >
Car -- Person : < owns
@enduml
要声明字段和方法,可以使用符号“:”后跟字段或方法的名称。系统检查括号,以便在方法和字段之间进行选择。
.. uml::
@startuml
'style options
skinparam monochrome true
skinparam circledCharacterRadius 9
skinparam circledCharacterFontSize 8
skinparam classAttributeIconSize 0
hide empty members
abstract class AbstractClass {
- privateField
+ publicField
# protectedField
~ packagePrivateField
- privateMethod()
+ publicMethod()
# protectedMethod()
~ packagePrivateMethod()
}
class Dummy {
{static} staticID
{abstract} void methods()
}
class Flight {
flightNumber : Integer
departureTime : Date
}
package "Classic Collections" {
abstract class AbstractList
abstract AbstractCollection
interface List
interface Collection
List <|-- AbstractList
Collection <|-- AbstractCollection
Collection <|- List
AbstractCollection <|- AbstractList
AbstractList <|-- ArrayList
class ArrayList {
Object[] elementData
size()
}
}
enum TimeUnit {
DAYS
HOURS
MINUTES
}
class Student {
Name
}
Student "0..*" -- "1..*" Course
(Student, Course) .. Enrollment
class Enrollment {
drop()
cancel()
}
@enduml
用例图¶
代码¶
图表¶
这是由sphinx plantuml扩展生成的。
代码¶
.. uml::
@startuml
actor "Main Database" as DB << Application >>
note left of DB
This actor
has a "name with spaces",
an alias
and a stereotype
end note
actor User << Human >>
actor SpecialisedUser
actor Administrator
User <|--- SpecialisedUser
User <|--- Administrator
usecase (Use the application) as (Use) << Main >>
usecase (Configure the application) as (Config)
Use ..> Config : <<includes>>
User --> Use
DB --> Use
Administrator --> Config
note "This note applies to\nboth actors." as MyNote
MyNote .. Administrator
MyNote .. SpecialisedUser
' this is a text comment and won't be displayed
AnotherActor ---> (AnotherUseCase)
' to increase the length of the edges, just add extras dashes, like this:
ThirdActor ----> (LowerCase)
' The direction of the edge can also be reversed, like this:
(UpperCase) <---- FourthActor
@enduml
活动图(新语法)¶
图表¶
代码¶
创建活动图有两种语法。该示例使用新语法(仍然不完整)。
.. uml::
@startuml
start
:first activity;
:second activity
with a multiline
and rather long description;
:another activity;
note right
After this activity,
are two 'if-then-else' examples.
end note
if (do optional activity?) then (yes)
:optional activity;
else (no)
if (want to exit?) then (right now!)
stop
else (not really)
endif
endif
:third activity;
note left
After this activity,
parallel activities will occur.
end note
fork
:Concurrent activity A;
fork again
:Concurrent activity B1;
:Concurrent activity B2;
fork again
:Concurrent activity C;
fork
:Nested C1;
fork again
:Nested C2;
end fork
end fork
repeat
:repetitive activity;
repeat while (again?)
while (continue?) is (yes, of course)
:first activity inside the while loop;
:second activity inside the while loop;
endwhile (no)
stop
@enduml
状态图¶
图表¶
由sphinx plantuml扩展生成。
代码¶
.. uml::
@startuml
[*] --> MyState
MyState --> CompositeState
MyState --> AnotherCompositeState
MyState --> WrongState
CompositeState --> CompositeState : \ this is a loop
AnotherCompositeState --> [*]
CompositeState --> [*]
MyState : this is a string
MyState : this is another string
state CompositeState {
[*] --> StateA : begin something
StateA --> StateB : from A to B
StateB --> StateA : from B back to A
StateB --> [*] : end it
CompositeState : yet another string
}
state AnotherCompositeState {
[*] --> ConcurrentStateA
ConcurrentStateA --> ConcurrentStateA
--
[*] --> ConcurrentStateB
ConcurrentStateB --> ConcurrentStateC
ConcurrentStateC --> ConcurrentStateB
}
note left of WrongState
This state
is a dead-end
and shouldn't
exist.
end note
@enduml