mkdocs (기술 문서 정리하기 좋은 tool)

오늘은!!!!!

 

 

mkdocs 입니다!

 

 

mkdocs를 사용하면 개발중인 프로젝트에 대한 정보를

markdown으로 정리하고

​

쉽게 문서화 할 수 있습니다.

​

사용법은

​

아래와 같습니다.

​

우선 anaconda3 혹은

python3와 pip3를 설치해 두신 상태

​

라고 가정하고 진행하겠습니다.

​

주요 설치 방식은

​

https://www.mkdocs.org/

MkDocs

MkDocs 공식 홈페이지에 친절하게 설명되어 있습니다.

​

설치는 아주 간단합니다!

pip install mkdocs

​

위와 같이 입력하면 설치가 완료 됩니다.

​

이제 Markdown 문서를 정리할 위치에 가서

문서정리를 시작해보겠습니다.

​

문서정리할 내용이 저장될 위치로 이동해서

​

mkdocs new 정리할 프로젝트 이름

위와 같이 입력합니다.

​

저는 C:\mydocs 폴더에서

아래와 같이 입력했습니다.

​

mkdocs new my-project

​

​

 

​

입력과정을 거치고 나면 위와 같이 되는 것을 보실수 있습니다.

​

설정한 프로젝트 이름의 폴더가 생기고

(저는 my-project 였습니다)

​

그 안에 docs 폴더와 mkdocs.yml이 생깁니다.

​

바로 한번 mkdocs를 실행해서 web에서 문서를 볼수 있도록 해볼까요?

​

문서 열기는

​

mkdocs serve

위 명령을 입력하시면 됩니다.

​

위를 보시면

​

어디에 열렸는지 알수 있는데

​

localhost의 8000번 포트에 열린 것을 알 수 있습니다.

​

8000번 포트로 가보면

​

​

위와 같은 웹사이트가 들어가지는 것을 보실 수 있습니다.

​

command와 Project layout 이라는 부분이 있네요.

​

자동생성된 docs 폴더안에 index.md 라는 file이 있는데 코드를 보면

​

위와 같이 제목으로서 작성된 문장이 3개 있습니다.

​

# Welcome to MkDocs

​

## Commands

​

## Project layout

​

세개가 있습니다.

​

그래서 아래와 같이 된것 입니다.

​

 

​

​

페이지를 추가하는 것은 그냥 해당 폴더에 markdown 파일을 추가하면 됩니다.

​

아래와 같이 작성하고 저장하면

​

​

​

페이지가 생성된 것을 알 수 있습니다.

​

이렇게 mkdocs를 간단하게 사용해봤는데요

​

위와 같은 UI가 맘에 드시면 그냥 사용하시면 되지만

​

좀 더 깔끔한 형태를 원하신다면

위 주소에서 찾아보시고 적용하시면 됩니다.

​

저는 ReadtheDocs를 적용해보도록 하겠습니다.

​

pip install mkdocs-rtd-dropdown

위와 같은 명령을 입력하셔서 read-the-docs를 설치하시고

​

서버를 종료하신 뒤에

(아까 mkdocs serve로 연 문서 서버를

ctrl + c 를 눌러서 닫으시면 됩니다.)

​

project 폴더에 있는

​

mkdocs.yml을 아래와 같이 수정하시고

다시 서버를 열면됩니다.

​

서버를 여는 건 아까와 같이

​

mkdocs serve를 입력하시면 됩니다.

​

이제 아까 주소였던

​

localhost:8000으로 돌아가보면

​

이렇게 테마가 바뀌어 있는것을 보실수 있습니다!

​

모두 mkdocs를 활용해서 진행하고 있는 프로젝트

멋지게 관리 하셨으면 좋겠습니다!!

​

그럼 다음에도 좋은 정보로 찾아오겠습니다~!

출처: https://m.blog.naver.com/doksg/221986849004