Skip to content

Commit

Permalink
update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
monitor1379 committed Nov 26, 2016
1 parent 4e33212 commit 1406415
Showing 1 changed file with 0 additions and 70 deletions.
70 changes: 0 additions & 70 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,76 +4,6 @@ More details about Sophon is in here: [Sophon](https://monitor1379.github.io/sop

## What is Sophon?

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
```


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]:

```
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.
"""
```


Use Sophon to parse the docstring and we get Markdown:

~~~
<span style="float:right;">[[source]](repo/blob/branch/__main__.py#L19)</span>
## dump
```python
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.
---
~~~

which is rendered by MkDocs with theme `yeti`:

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

Much more legible, no?

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
Expand Down

0 comments on commit 1406415

Please sign in to comment.