add mddocs/user_guide/installation.md

monitor1379 · Nov 25, 2016 · a2de909 · a2de909
1 parent 51ca41e
commit a2de909
Show file tree

Hide file tree

Showing 15 changed files with 205 additions and 126 deletions.
diff --git a/examples/api/API_of_mycode.md b/examples/api/API_of_mycode.md
@@ -0,0 +1,61 @@
+
+
+## Person
+
+```python
+mycode.Person(name, age=18)
+```
+
+This is a class of Person.
+
+**Arguments**
+
+- **name**: `str`. The name of the Person instance.
+- **age**: `int`. Defaults to 18. The age of the Person instance.
+
+**Examples**
+
+You could create a Person instance in this way:
+```python
+batman = Person('Bruce Wayne')
+elder = Person('you-know-who`, 99)
+```
+
+---
+
+
+
+## speak
+
+```python
+mycode.Person.speak(message)
+```
+
+Speak something.
+
+**Argument:**
+
+- **message**: `str`. Something to speak.
+
+**Return:**
+
+`None`.
+
+---
+
+
+
+## show_info
+
+```python
+mycode.show_info(person)
+```
+
+Show the personal information of the given person.
+
+**Argument**
+
+- **person**: `Person`. The person.
+
+---
+
diff --git a/examples/mycode.py b/examples/mycode.py
@@ -8,19 +8,11 @@ class Person(object):
         name: `str`. The name of the Person instance.
         age: `int`. Defaults to 18. The age of the Person instance.
 
-    # Attributes
-        name: `str`. The name of the Person instance.
-        age: `int`. Defaults to 18. The age of the Person instance.
-        sex: `str`. Defaults to 'male'. The sex of the Person instance.
-
-    # Note
-        This is Note.
-
     # Examples
         You could create a Person instance in this way:
         ```python
         batman = Person('Bruce Wayne')
-        elder = Person('you-know-who`, 99)
+        elder = Person('you-know-who', 99)
         ```
     """
 
@@ -51,6 +43,9 @@ def show_info(person):
 
 
 if __name__ == '__main__':
-    p = Person('monitor1379')
-    p.speak('Are you OK?')
-    show_info(p)
+    from sophon.parsers import SophonParser
+    parser = SophonParser()
+    print parser.parse_from_class(Person)
+    print parser.parse_from_function(Person.speak)
+    print parser.parse_from_function(show_info)
+
diff --git a/examples/sophon.yml b/examples/sophon.yml
@@ -0,0 +1,11 @@
+code_dir: .
+build_dir: api
+pages:
+- page: API_of_mycode.md
+  tags:
+  - tag:
+    classes:
+    - mycode.Person
+    functions:
+    - mycode.Person.speak
+    - mycode.show_info
diff --git a/mddocs/api/sophon/API.md b/mddocs/api/sophon/API.md
@@ -11,7 +11,7 @@ This is some API documentations of Sophon.
 ## Parser
 
 ```python
-sophon.parsers.Parser.Parser()
+sophon.parsers.Parser()
 ```
 
 Top level base class of parsers.
@@ -26,7 +26,7 @@ Top level base class of parsers.
 ## ReStructuredTextParser
 
 ```python
-sophon.parsers.ReStructuredTextParser.ReStructuredTextParser()
+sophon.parsers.ReStructuredTextParser()
 ```
 
 Support soon.
@@ -40,7 +40,7 @@ Support soon.
 ## GoogleDocParser
 
 ```python
-sophon.parsers.GoogleDocParser.GoogleDocParser()
+sophon.parsers.GoogleDocParser()
 ```
 
 Support soon.
@@ -54,7 +54,7 @@ Support soon.
 ## NumPyDocParser
 
 ```python
-sophon.parsers.NumPyDocParser.NumPyDocParser()
+sophon.parsers.NumPyDocParser()
 ```
 
 Support soon.
@@ -66,7 +66,7 @@ Support soon.
 ## SophonParser
 
 ```python
-sophon.parsers.SophonParser.SophonParser()
+sophon.parsers.SophonParser()
 ```
 
 A docstring parser for parsing Sophon style docstring to Markdown.
@@ -365,12 +365,12 @@ Get the definition position of obj in source file, then link it to GitHub repo.
 
 
 
-<span style="float:right;">[[source]](https://github.com/monitor1379/sophon/blob/master/sophon/build.py#L25)</span>
+<span style="float:right;">[[source]](https://github.com/monitor1379/sophon/blob/master/sophon/cmd/build.py#L25)</span>
 
 ## build_from_yaml
 
 ```python
-sophon.build.build_from_yaml(config_fn)
+sophon.cmd.build.build_from_yaml(config_fn)
 ```
 
 Build documentations of python project given the configuration filename.

diff --git a/mddocs/index.md b/mddocs/index.md
@@ -115,7 +115,8 @@ Features:
     you only need one command to build you API documentation.
 
 
-You can find more details in **User Guide**.
+You can find more details in **[User Guide/Installation](user_guide/installation.md)** or
+**[User Guide/Getting Started](user_guide/getting_started.md)**.
 
 
 ## What does "Sophon" mean?

diff --git a/mddocs/sophon_build.py b/mddocs/sophon_build.py
@@ -1,9 +1,9 @@
 # encoding: utf-8
 
-import sophon
+from sophon.cmd.build import build_from_yaml
 
 def run():
-    sophon.cmd.build.build_from_yaml('sophon.yml')
+    build_from_yaml('sophon.yml')
 
 
 if __name__ == '__main__':

diff --git a/mddocs/user_guide/getting_started.md b/mddocs/user_guide/getting_started.md
@@ -1,24 +1,63 @@
-# Installation
+# Getting started
 
-Download Sophon from GitHub:
+Now let's create your first API documentation. 
+
+Assuming the path of your Python module is `E://myproject//mycode.py`,
+and the code is:
 
-```bash
-$ git clone git@github.com:monitor1379/sophon.git
+```
+def hello_world(message):
+    """Speak a message.
+
+    Speak a message to the world.
+    
+    # Argument
+        message: `str`. The message you want to speak.
+               
+    # Return
+        `None`.
+    """
+    pass
 ```
 
-Install Sophon using `pip`:
 
-```bash
-$ cd sophon
-$ pip install .
+Getting started is super easy:
+
+```
+$ sophon new
+[2016-11-25 09:44:48,809][INFO]: Creating Sophon configuration file: sophon.yml...
+[2016-11-25 09:44:48,812][INFO]: Create done!
 ```
 
-# Create your first API documentation
+1 seconds latter the configuration file `sophon.yml` has been created for you.
+
+`sophon.yml` is the only configuration file, 
+it decides which documentation of classes or functions will be generated and inserted to where.
+Note that the `sophon.yml` is not necessary to be in the same directory as `mycode.py`.
+
+Open the `sophon.yml`, edit it:
+```python 
+code_dir: E://myproject
+build_dir: api
+pages:
+- page: API_of_mycode.md
+  tags:
+  - tag: 
+    functions:
+    - mycode.speak
+```
+
+- `code_dir` means the path of your Python project, 
+this path will be add to the `sys.path` by Sophon so Sophon can `import` it.
+Note that it can be absolute path or relative path to `sophon.yml`.
+
+- `build_dir` means the directory of output documentations.
+Note that it can be absolute path or relative path to `sophon.yml`.
+
+- `pages` includes a list of `page`, each `page` means a Markdown file.
+
 
-Now let's create your first API documentation. 
 
-Assuming the path of your Python module is `/home/batsy/mycode.py`,
-and the code is:
 
 ```
 # encoding: utf-8
@@ -31,19 +70,11 @@ class Person(object):
         name: `str`. The name of the Person instance.
         age: `int`. Defaults to 18. The age of the Person instance.
 
-    # Attributes
-        name: `str`. The name of the Person instance.
-        age: `int`. Defaults to 18. The age of the Person instance.
-        sex: `str`. Defaults to 'male'. The sex of the Person instance.
-
-    # Note
-        This is Note.
-
     # Examples
         You could create a Person instance in this way:
         ```python
         batman = Person('Bruce Wayne')
-        elder = Person('you-know-who`, 99)
+        elder = Person('you-know-who', 99)
         ```
     """
 
@@ -63,25 +94,9 @@ class Person(object):
         """
         print('[{}]: {}'.format(self.name, message))
 
-
-def show_info(person):
-    """Show the personal information of the given person.
-
-    # Argument
-        person: `Person`. The person.
-    """
-    print('name:{}, age:{}'.format(person.name, person.age))
-
-
-if __name__ == '__main__':
-    p = Person('monitor1379')
-    p.speak('Are you OK?')
-    show_info(p)
 ```
 
 
-
-
 Example Sophon Style Python Docstrings
 
 

diff --git a/mddocs/user_guide/installation.md b/mddocs/user_guide/installation.md
@@ -0,0 +1,14 @@
+# Installation
+
+Download Sophon from GitHub:
+
+```bash
+$ git clone git@github.com:monitor1379/sophon.git
+```
+
+Install Sophon using `pip`:
+
+```bash
+$ cd sophon
+$ pip install .
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -12,6 +12,7 @@ theme: yeti
 pages:
 - Home: index.md
 - User Guide:
+  - Installation: user_guide/installation.md
   - Getting Started: user_guide/getting_started.md
   - Sophon Style Python Docstrings: user_guide/sophon_style_python_docstrings.md
   - Configuration: user_guide/configuration.md

diff --git a/sophon/__init__.py b/sophon/__init__.py
@@ -1,7 +1,6 @@
 # encoding: utf-8
 from .cmd import build
 from .cmd import new
-from . import log
 from . import parsers
 from . import utils
 

diff --git a/sophon/__main__.py b/sophon/__main__.py
@@ -1,10 +1,22 @@
 # encoding: utf-8
 
 import click
+import logging
 
 from sophon import __version__
 from sophon.cmd import new, build
-from sophon.log import ConsoleLogger
+
+
+def create_log():
+    log = logging.getLogger("sophon")
+    log.setLevel(logging.DEBUG)
+    formatter = logging.Formatter("[%(asctime)s][%(levelname)s]: %(message)s ")
+    ch = logging.StreamHandler()
+    ch.setFormatter(formatter)
+    log.addHandler(ch)
+
+
+create_log()
 
 help_build = 'Build API documentations.'
 help_new = 'Create a configuration file.'
@@ -23,18 +35,18 @@ def cli():
 @cli.command('build', help=help_build)
 @click.option('-f', '--config-file', type=click.File('r'), default=default_config_file, help=help_config_file)
 def run_sophon_build(config_file):
-    logger = ConsoleLogger()
-    logger.info('Specify config_file:{}'.format(config_file.name))
+    log = logging.getLogger(__name__)
+    log.info('Specify config_file:{}'.format(config_file.name))
     config_file.close()
     build.build_from_yaml(config_file.name)
 
 
 @cli.command('new', help=help_new)
 def run_sophon_new():
-    logger = ConsoleLogger()
-    logger.info('Creating Sophon configuration file: sophon.yml...')
+    log = logging.getLogger(__name__)
+    log.info('Creating Sophon configuration file: sophon.yml...')
     new.new_yaml()
-    logger.info('Create done!')
+    log.info('Create done!')
 
 
 if __name__ == '__main__':