카피캣으로 시작하는 오픈소스

Introduction of Plate(python slate : API Documentation Tool based markdown)

Transcript

1. ஠ೖமਵ۽ द੘ೞח য়೑ࣗझ
   ash84
   

   View Slide

2. ash84
   • Developer
   • sh84.ahn@gmail.com
   • ash84.net
   • @sh84ahn
   • github.com/AhnSeongHyun
   
   

   View Slide

3. ੉۠ ೐۽ં౟ܳ ೞҊ ੓णפ׮.
   • Plate : API Documentation Tool based on markdown.
   • https://github.com/Plate-Project/plate
   • http://plate-project.github.io/
   
   

   View Slide

4. ѐߊೞѱ ػ ҅ӝ
   • ੑࢎ 3ѐਘର(नੑ਷ ইש), ೠହ ੄਄݅ খࢸ दӝ
   • API ੘স ੹, ࢸ҅ ୡউ ੘সҗ ೣԋ API ޙࢲച ో ઑࢎ
   • Ѿઁ ҙ۲ API ࢎ੉౟ٜਸ ઱۽ ଵҊ
   
   

   View Slide

5. more test
   • Swagger
   • http://petstore.swagger.io/
   • I/O Docs
   • https://github.com/mashery/iodocs
   • http://blog.outsider.ne.kr/990
   
   

   View Slide

6. more doc
   
   • Slate
   • https://github.com/tripit/slate
   • Atlassian/Confulence
   

   View Slide

7. Stripe API Docs
   

   View Slide

8. ҶҶҶ
   • ӝઓߑध - *.docx, *.xlsx + sample code
   • asp.net_example.zip, jsp_example.zip
   • সؘ੉౟о औ૑ ঋ׮.
   
   

   View Slide

9. ҶҶҶ
   • Stripe э਷ API ޙࢲച ࢎ੉౟ܳ ੉ਊೞݶ..
   • API ܳ पઁ ௏٘৬ ೣԋ ࠅࣻ ੓׮ח ੢੼.
   • APIܳ সؘ੉౟ ೞ؊ۄب, ખ ؊ औѱ ޙࢲ৬ ௏٘ܳ э੉ সؘ੉౟ оמ.
   
   

   View Slide

10. ׹੿ց - slate
    • slate ۽ ੿ೞҊ ࢓ಝࠁӝ द੘.
    • য঺, ੉Ѥ ܖ࠺. ܖ࠺ח ࢎیੑפ׮.
    
    

    View Slide

11. ࠙ࢳ
    • ҳࢿ
    • middleman : static site generator based Ruby
    • layout.erb - మ೒݁
    • index.md - APIޙࢲ
    • ѾҴ..
    1. index.md ਸ ߸ജ
    2. middleman ਸ ੉ਊ೧ࢲ layout.erb ী ֍Ҋ
    3. HTML ۽ ୹۱.
    
    

    View Slide

12. conv2python
    
    • ખ؊ ੊ࣼೠ ঱য৬ ജ҃ ࢎਊ. ࢎप਷ slate ج۰ࠁ׮ ૑୛ࢲ…
    • ౱ղ ઱ ঱য۽ ౵੉ॆਸ ޻Ҋ ੓ח ࢚క
    • ܖ࠺৬ о੢ ࠺तೠ?
    

    View Slide

13. conv2python
    
    • Middleman TO Flask
    • jinja2 template
    • layout.erb to /templates/index.html
    

    View Slide

14. conv2python
    
    • markdown to html
    • markdown : ߸ജ ߂ ׮নೠ ഛ੢ ݽٕ ઁҕ
    • fence_codes : markdown code block to
    • tables : markdown table syntax to
    

    import markdown

    return markdown.markdown(md_text, extensions=["fenced_code", "tables"])

    

    View Slide

15. conv2python
    
    ```python

    codes

    ```

    

    ```java 

    codes

    ```
    

    codes

    

    

    codes

    
    markdown html
    

    View Slide

16. conv2python
    
    • Code Syntax Highlighting
    • pygments : Python syntax highlighter
    • ׮নೠ ೐۽Ӓې߁ & ݃௼স ঱য ޙߨ ૑ਗ
    

    from pygments import highlight

    from pygments.lexers import PythonLexer

    from pygments.lexers import JavaLexer

    from pygments.formatters import HtmlFormatter

    

    highlighted = highlight(code, PythonLexer(), HtmlFormatter())

    highlighted = highlight(code, JavaLexer(), HtmlFormatter())

    

    View Slide

17. 
    ߸ജೞҊ, ֍ਵݶ, ՘.
    

    View Slide

18. slate-flask ۽ github ҕѐ
    • ੉ਬ :
    • ইө਑.
    • ա୊ۢ Ruby ী ੊ࣼೞ૑ ঋ਷ ࢎۈب ੓૑ ঋਸө.
    ҕѐ ೞա݃ա. য়೑݅ ػ.
    • ॶҔਸ ଺ইࠁ੗. ইפ ղо ॳ੗. ঌ߄ೞח ࢲߡAPI ޙࢲചী ੸ਊ.
    • ॄࠁפ, উજ਷ ࠗ࠙੉ ࠁ੉ӝ द੘.
    
    

    View Slide

19. ӝמ୶о
    • ݣ౭ ݃௼׮਍ ӝמ ୶о
    • watchdog ӝמ ୶о
    
    

    View Slide

20. ݣ౭ ݃௼׮਍ ӝמ
    • ੿ഋചػ ٣۩షܻо ইצ ࢎਊ੗о ҃۽ܳ ૑੿.
    • ݾର ࢚ী ಴दغח ࣽࢲب ੿ೞب۾ ૑੿.
    • index.json
    {

    "ORDER":

    [

    "Introduction.md",

    "Signup.md",

    "Signin.md", 

    "Notice.md", 

    "Notice.jp.md", 

    "Notice.fr.md"

    ]

    }
    

    

    
    

    View Slide

21. • ݅ড, API ޙࢲо ࣻ੿ػ׮ݶ?
    • ࢲߡܳ Տ׮.
    • API ޙࢲܳ Ҋ஘׮.
    • ׮द ࢲߡܳ ৢܽ׮.
    • ޙࢲܳ ࣻ੿ೞݶ ߄۽ ࢲߡо ੗زਵ۽ ੋध೧ࢲ ղਊਸ ߄Լ઱੗.
    
    

    View Slide

22. watchdog
    • ࢲߡ۽ ڸ਋ݶ, ߄۽ хद द੘.
    • ޙࢲо ߸҃غݶ, ׮਺ ਃ୒द ׮द html ٜ݅ӝ ࣻ೯
    
    

    View Slide

23. EMOCON 2015 F/W ળ࠺ೞݶࢲ ୶оೠ ղਊٜ.
    • slate-flask to Plate-Project/plate : organization
    • postman2md
    • multi-language searching
    • static html
    
    

    View Slide

24. ࢲߡ API ѐߊद੄ ಁఢ
    • ࢎਊೠ పझ౴ਸ ޙࢲ۽ ٜ݅ࣻ ੓૑ ঋਸө?
    postman2md
    • postman collection json ਸ markdown ਵ۽ ߸ജ
    • ߸ജػ markdown ਸ ޙࢲചী ੉ਊ(plateী ੉ਊ)
    • postman collection json with plate
    
    testing
    "1*
    %FTJHO
    doc
    dev
    

    View Slide

25. Ѩ࢝੄ ޙઁ : lunr.js ੉ਊ
    • ৔য݅ਸ ૑ਗೞח ޙઁ, ׮Ҵয ૑ਗ੄ ੉ग
    • lunr-languages ܳ plate ী োز, ݻ ѐ੄ ׮Ҵয Ѩ࢝ оמ.
    • അ੤ ೠҴযо হযࢲ lunr.kr.js ܳ ٜ݅Ҋ ੓ח ઺
    
    

    View Slide

26. static html
    • ࢎप ௼ѱ ࢤпೞ૑ ঋও؍ ӝמ.
    • github.io э਷ Ҕী ৢܻѢա Apacheী ৢܽ׮ݶ
    • ਗې Flask ח jinja2 template ܳ ੉ਊ, ߸ജػ HTML ਸ ੷੢
    • http://plate-project.github.io/
    
    

    View Slide

27. খਵ۽੄ ҅ദ
    • ী٣ఠ
    • పझ౴ࠗ࠙੄ ୶о : slateীب Բળೠ ੉ग
    • ஠ೖம੄ ఎೖ - Front-End
    • ઑӘ਷ ׮ܲ ߑೱਵ۽੄ API Documentation Toolਸ ٜ݅Ҋ र׮.
    
    

    View Slide

28. য়೑ࣗझ द੘ೞӝ
    • ௏٘સӝ vs. ஠ೖம
    • ੢ױ੼੉ ੓ח ٠, ѐੋ੄ ࢿೱ
    
    

    View Slide

29. যڌѱ ҅ࣘ ਬ૑ೡࣻ ੓חо?
    • ೠߣ द੘ೠѪਸ ҅ࣘ ਬ૑ೞחѪ਷ औ૑о ঋ਺.
    • ౠ൤ ஠ೖம਷ ؊ Ӓ۠٠.
    • ॄࠁҊ ҅ࣘ ѐࢶೡ Ѣܻܳ ݅٘ח Ѫ੉ ੗ӓ੉ ؽ.
    • ૑ࣘ੸ਵ۽ ೡࣻ ੓חѪਸ ࢶఖೞӡ.
    
    

    View Slide

30. ૑ெࠁҊ ੓ӝ.
    
    • issue, pull request
    • ೙ਃೠ ӝמٜਸ ଺ইղח ઺.
    

    View Slide

31. যڌѱ જ਷ য়೑ࣗझо ؼࣻ ੓ਸө?
    • fork count? star?
    • ৈ੹൤ ݽܰѷ਺. ࣼઁ
    • ଺ইоח җ੿
    
    

    View Slide

32. For me
    • ૑ࣘ੸ਵ۽ ѐߊೡ Ѣܻ, daily commit
    • ҙ۲ػ ׮নೠ য়೑ࣗझী ؀ೠ ੽Ӕ.
    
    

    View Slide

33. Thank you
    

    View Slide