Skip to content

Commit

Permalink
modified "README.md"
Browse files Browse the repository at this point in the history
  • Loading branch information
@monitor1379
monitor1379 committed Nov 26, 2016
1 parent e1e9892 commit 4e60cc7
Showing 1 changed file with 105 additions and 128 deletions.
233 changes: 105 additions & 128 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,165 +1,142 @@
# Sophon
# Sophon: Automatic API Markdown Documentation Generation for Python

More details about Sophon is in here: [Sophon](monitor1379.github.io/sophon).

## What is Sophon?

Sophon is a tool that could automatically generate Markdown-format API documentation from Python code.
Before I tell you what is Sophon, let me ask you a question:
Are you ever tired of writing docstrings that look like this?

```
def dump(obj, filename, encrypt=False):
"""Dump a object into file.
:param obj: A Python object
:type obj: any
:param filename: Filename of the file to dump
:type filename: str
:param encrypt: Whether or not to encrypt the file
:type encrypt: bool
:returns: Whether or not to dump successfully
:rtype: bool
"""
pass
```

**markdown API documentation automatic generator** that

makes it easy to create
intelligent and beautiful documentation,
written by Zhenpeng Deng and licensed under the MIT license.
reStructuredText is great, but docstring written in reST creates visually dense, and hard to read.
Compare the jumble above to the same thing rewritten according to the [Sophon Style Python Docstring][8]:

## Why Sophon?
```
def dump(obj, filename, encrypy=False):
"""Dump a object into file.
# Arguments
obj: `any`. A Python object.
filename: `str`. Filename of the file to dump.
encrypt: `bool`. Whether or not to encrypt the file.
# Return
`bool`: Whether or not to dump successfully.
"""
```

Features:

- Flexible.
- Markdown formats.
- Automatically generate API documentation.
- Works on Windows, Linux and macOS.
Use Sophon to parse the docstring and we get Markdown:

~~~
<span style="float:right;">[[source]](repo/blob/branch/__main__.py#L19)</span>
### What does "Sophon" mean?
## dump
**Sophon** is the official translation of "**智子**" in 《Rememberance of Earth's Past II: The Dark Forest》
which is written by the famous Chinese science fiction writer named **Cixin Liu(刘慈欣)**.
```python
dump(obj, filename, encrypy=False)
```
Dump a object into file.
**Sophon** is a word amalgamation of `Sophia/sophist/sophisticated`, meaning **wisdom**,
and `Proton/Electron/Neutron/Photon`, meaning **particle**,
consisting of a supercomputer embedded into a single proton that could fold itself to eleven space dimensions.
## Installation
**Arguments**
- **obj**: `any`. A Python object.
- **filename**: `str`. Filename of the file to dump.
- **encrypt**: `bool`. Whether or not to encrypt the file.
## Usage
**Return**
- Extra python file.
- **`bool`**: Whether or not to dump successfully.
Extra the docstring of `py-file` into `md-file`.
Sophon will create a new markdown file if `md-file` argument isn't given.
---
~~~

Given a python file named 'test.py':
which is rendered by MkDocs with theme `yeti`:

"""Here is Title

This is module abstraction.


Here is some example code of how to use this module.

```python
def how_to_use():
pass
```
"""


def foo(bar, baz=90):
"""function description.
can new line.

# Argument:
bar: str.
some description of bar.

baz: or some description here.

# Return:
None

# Note:
This is note of function.

# Example:
you can use `foo` in this way.

```python
foo('dzp')
foo('dzp', 22)
```

"""
pass
![dump()](img/dump_of_index.png)

This way can generate markdown document.
```bash
$ sophon generate <py-file> [output-md-file]
```
Much more legible, no?

If `output-md-file` argument is not given,
then Sophone will generate a markdown file with the same name as py-file in current directory.
As you see,
Sophon is a tool that could **automatically generate Markdown-format API documentations** from Python docstring,
just like **Epydoc** (supports reStructuredText, Javadoc, plaintext)
and **Napoleon** (Sphinx extension that enables Sphinx to parse both NumPy and Google
style docstrings to reStructuredText).

# Here is Title
This is module abstraction.


Here is some example code of how to use this module.

```python
def how_to_use():
pass
```

## foo
```
test.foo(bar, baz=90)
```

function description.
can new line.

### Argument

- bar: str.
some description of bar.

- baz: or some description here.
Sophon is written by [Zhenpeng Deng(monitor1379)][1] and licensed under the MIT license.

## Why Sophon?

Features:

- **Support different kinds of docstrings.**
Sophon mainly supports to parse docstring with the following styles and converts them to Markdown:
- Sophon style docstring
- (Coming Soon) [Google style][4], the style recommended by [Khan Academy][5]
- (Coming Soon) [NumPy style][6]

### Return
None
Sophon also supports to parse every docstring in Python project,
including docstrings on: `classes`, `methods` and `functions`
(`modules`, `attributes` and `variables` will be supported soon)

### Note
This is note of function.

### Example
you can use `foo` in this way.
- **Output Markdown format documentations.**
Markdown is a way to write contents for the web.
Unlike cumbersome word processing applications or other markup languages with complicated syntax,
text written in Markdown can be easy to read, easy to write and easily shared for between computers,
mobile phones, and people.
Though it does not do anything fancy like change the font size, color or type by itself,
it has enough stuffs to write an API documentation for your python projects.

```
foo('dzp')
foo('dzp', 22)
```




```bash
$ sophon compile <md-file>
```
Another important reason of choosing Markdown is that there are some remarkable tools for Markdown
to build beautiful documentations or blogs such as
[MkDocs(Project documentation with Markdown)][2] or [Hexo(A fast, simple & powerful blog framework)][3].

- **Easily and Highly customizable.**
Sophon uses [YAML: YAML Ain't Markup Language][7] as the format of configuration file.
By configuring and providing Markdown template files, you can freely organize your documentation,
or open some advanced features such as linking API to source files deposited on GitHub repositories.

```bash
$ sophon <py-file> [md-file]
```

- Build markdown file.
- **One-Command build.**
you only need one command to build you API documentation.


- project mode.
You can find more details in **[User Guide/Installation](user_guide/installation.md)** or
**[User Guide/Getting Started](user_guide/getting_started.md)**.


more information in here:[A Guide to Sophon documentation](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)
## What does "Sophon" mean?

**Sophon** is the official translation of "**智子**" in 《Rememberance of Earth's Past II: The Dark Forest》
which is written by the famous Chinese science fiction writer named **Cixin Liu(刘慈欣)**.

## "What does "Sophon" mean?"

"Sophon"是刘慈欣著名作品《三体2：黑暗森林》中的"智子"一词的官方英文翻译。
**Sophon** is a word amalgamation of `Sophia/sophist/sophisticated`, meaning **wisdom**,
and `Proton/Electron/Neutron/Photon`, meaning **particle**,
consisting of a supercomputer embedded into a single proton that could fold itself to eleven space dimensions.

"Sophon"是一个复合词，在英文中，"soph-"通常表示"智慧"的意思，比如"sophist"为"哲学家"，
"sophisticated"为"复杂玄妙的"的意思。
而"-on"表示"粒子"，比如离子（ion），电子（Electron），质子(proton)，中子（Neutron），强子（hadron），
玻色子（boson），胶子（Gluon），光子（photon）等等。

在原著中，智子表示的是一种能够将自身折叠到11维粒子的超级计算机。
[1]: https://github.com/monitor1379
[2]: http://www.mkdocs.org
[3]: https://hexo.io
[4]: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google
[5]: https://sites.google.com/a/khanacademy.org/forge/for-developers/styleguide/python#TOC-Docstrings
[6]: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy
[7]: http://www.yaml.org/
[8]: user_guide/sophon_style_python_docstrings

0 comments on commit 4e60cc7

Please sign in to comment.