Awesome

Plate

Plate is API Documentations Tool based on Markdown(md). Convert Slate based on Ruby-Middleman to Python-Flask based. And add some different functions for usages.

Example site is plate-project.github.io. Plate document is plate.readthedocs.org.

Features

• Configuration File(config.json) : Set a title, programming languages for example codes using config.json based on JSON Format. Also set the path of the API documents and TOC(Table of contents). Anyone can easily set up.

• Support Multi-API documents : plate support multiple API documents(multi markdown format files) for efficient management and amount of documents. As you with, use one markdown file or separate markdown files by API or another criterion. Also you can set the output order using TOC(index.json).

• Support dynamic changes of documents : You can update the changes of API documents without restarting server. When web page refresh, if exist any changes, plate reload API documents. Users only focus on writing API documents.

• Make Static HTML : Convert Markdown(md) to Static HTML using jinja2 template. Use this on github.io and static html service or offline.

• Multi-Languages Searching : To support searching various languages such as Japanese, French, German, etc, use not only lunr.js but also lunr-languages.

• Code Copy : It can be easily copy the example codes without mouse drag and drop, immediately apply this to your codes. Set <code>CLIPBOARD</code> in config.json, can copy codes using clicking copy link.

Plate is very easy for any developers. First of all, follow below Getting Start. And then you have any problems, immediately notify(email, issue board, anything). Always, plate is ready for you.

Getting Start

Support Python Version

• Python, version 2.7 ~ 3.4

Prerequisites

• requirements.txt have all libraries for running plate
• If you install using quick-start.py, automatically install all libraries.

Quick Start with Server

1. Clone plate to your hard drive with git clone https://github.com/Plate-Project/plate.git

2. cd plate

3. Install your API document web pages using quick-start.py.

4. Start with server: python plate.py

   > git clone https://github.com/Plate-Project/plate.git
   > cd plate
   > python install.py
   ...
   Welcome plate v0.2.6
   Start your API Document system.
   
   Typing API document name :<Typing your project>
   what is API document name? is "<your project>"
   
   Rename plate to  "<your project>" ...
   Complete. Enjoy developing.
   
   > cd ../<your project>
   > python plate.py
   

Quick Start with Static HTML

Start with static html: python pst.py -f <conf file>

> python pst.py -f config.json

config.json(configuration file)

• path : ./config.json

{
    "PORT"               : 8888,
    "TITLE"              : "API Document",
    "LOGO_TITLE"         : "API Document",
    "SEARCH_ON"          : true,
    "SUPPORT_LANG"       : ["shell", "python"],
    "API_DOC_PATH"       : "./document",
    "API_DOC_INDEX_PATH" : "index.json",
    "COPYRIGHT"          : "© 2016 plate",
    "FAVICON"            : "favicon.ico",
    "CLIPBOARD"          : true,
    "STATIC" : {
        "DIR" : "./plate_static",
        "HTML" : "index.html"
    }
}

index.json(Table of contents)

• path : ./document/index.json

{
    "ORDER":
    [
        "Introduction.md",
        "Signup.md",
        "Signin.md"
    ]
}

Version v0.2.6

• V0.2.6
  • Add Test Cases.
• V0.2.5
  • Change basic structures
  • Add Unit Testing
• v0.2.4
  • Apply Sphinx documentation

More Info

More Information such as example, usage, internal, advanced is here. plate.readthedocs.org

Contributing

Any suggestions submit a issue. Show me the pull requests.

Special Thanks

• slate
• pygments
• lunr-languages

License

Copyright 2016 Plate

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.