plate

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

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

3. 이런 프로젝트를 하고 있습니다.
• Plate : API Documentation Tool based on markdown.
• https://github.com/Plate-Project/plate
• http://plate-project.github.io/
3

4. 개발하게 된 계기
• 입사 3개월차(신입은 아님), 한창 의욕만 앞설 시기
• API 작업 전, 설계 초안 작업과 함께 API 문서화 툴 조사
• 결제 관련 API 사이트들을 주로 참고
4

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

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

7. Stripe API Docs

8. 굳굳굳
• 기존방식 - *.docx, *.xlsx + sample code
• asp.net_example.zip, jsp_example.zip
• 업데이트가 쉽지 않다.
8

9. 굳굳굳
• Stripe 같은 API 문서화 사이트를 이용하면..
• API 를 실제 코드와 함께 볼수 있다는 장점.
• API를 업데이트 하더라도, 좀 더 쉽게 문서와 코드를 같이 업데이트 가능.
9

10. 답정너 - slate
• slate 로 정하고 살펴보기 시작.
• 어엇, 이건 루비. 루비는 사랑입니다.
10

11. 분석
• 구성
• middleman : static site generator based Ruby
• layout.erb - 템플릿
• index.md - API문서
• 결국..
1. index.md 을 변환
2. middleman 을 이용해서 layout.erb 에 넣고
3. HTML 로 출력.
11

12. conv2python
12
• 좀더 익숙한 언어와 환경 사용. 사실은 slate 돌려보다 지쳐서…
• 팀내 주 언어로 파이썬을 밀고 있는 상태
• 루비와 가장 비슷한?

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

14. conv2python
14
• markdown to html
• markdown : 변환 및 다양한 확장 모듈 제공
• fence_codes : markdown code block to <pre></pre>
• tables : markdown table syntax to <table></table>
import markdown
return markdown.markdown(md_text, extensions=["fenced_code", "tables"])

15. conv2python
15
```python
codes
```
```java
codes
```
<pre class="highlight python">
codes
</pre>
<pre class="highlight java">
codes
</pre>
markdown html

16. conv2python
16
• 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())

17. 17
변환하고, 넣으면, 끝.

18. slate-flask 로 github 공개
• 이유 :
• 아까움.
• 나처럼 Ruby 에 익숙하지 않은 사람도 있지 않을까.
공개 하나마나. 오픈만 된.
• 쓸곳을 찾아보자. 아니 내가 쓰자. 알바하는 서버API 문서화에 적용.
• 써보니, 안좋은 부분이 보이기 시작.
18

19. 기능추가
• 멀티 마크다운 기능 추가
• watchdog 기능 추가
19

20. 멀티 마크다운 기능
• 정형화된 디렉토리가 아닌 사용자가 경로를 지정.
• 목차 상에 표시되는 순서도 정하도록 지정.
• index.json
{
"ORDER":
[
"Introduction.md",
"Signup.md",
"Signin.md",
"Notice.md",
"Notice.jp.md",
"Notice.fr.md"
]
}
20

21. • 만약, API 문서가 수정된다면?
• 서버를 끈다.
• API 문서를 고친다.
• 다시 서버를 올린다.
• 문서를 수정하면 바로 서버가 자동으로 인식해서 내용을 바꿔주자.
21

22. watchdog
• 서버로 띄우면, 바로 감시 시작.
• 문서가 변경되면, 다음 요청시 다시 html 만들기 수행
22

23. EMOCON 2015 F/W 준비하면서 추가한 내용들.
• slate-flask to Plate-Project/plate : organization
• postman2md
• multi-language searching
• static html
23

24. 서버 API 개발시의 패턴
• 사용한 테스팅을 문서로 만들수 있지 않을까?
postman2md
• postman collection json 을 markdown 으로 변환
• 변환된 markdown 을 문서화에 이용(plate에 이용)
• postman collection json with plate
24
testing
API
Design
docdev

25. 검색의 문제 : lunr.js 이용
• 영어만을 지원하는 문제, 다국어 지원의 이슈
• lunr-languages 를 plate 에 연동, 몇 개의 다국어 검색 가능.
• 현재 한국어가 없어서 lunr.kr.js 를 만들고 있는 중
25

26. static html
• 사실 크게 생각하지 않았던 기능.
• github.io 같은 곳에 올리거나 Apache에 올린다면
• 원래 Flask 는 jinja2 template 를 이용, 변환된 HTML 을 저장
• http://plate-project.github.io/
26

27. 앞으로의 계획
• 에디터
• 테스팅부분의 추가 : slate에도 꾸준한 이슈
• 카피캣의 탈피 - Front-End
• 조금은 다른 방향으로의 API Documentation Tool을 만들고 싶다.
27

28. 오픈소스 시작하기
• 코드줍기 vs. 카피캣
• 장단점이 있는 듯, 개인의 성향
28

29. 어떻게 계속 유지할수 있는가?
• 한번 시작한것을 계속 유지하는것은 쉽지가 않음.
• 특히 카피캣은 더 그런듯.
• 써보고 계속 개선할 거리를 만드는 것이 자극이 됨.
• 지속적으로 할수 있는것을 선택하길.
29

30. 지켜보고 있기.
30
• issue, pull request
• 필요한 기능들을 찾아내는 중.

31. 어떻게 좋은 오픈소스가 될수 있을까?
• fork count? star?
• 여전히 모르겠음. 숙제
• 찾아가는 과정
31

32. For me
• 지속적으로 개발할 거리, daily commit
• 관련된 다양한 오픈소스에 대한 접근.
32

33. Thank you