Docsify, Lefthook, friends와 함께 OSS 문서 저장

"A program is only as good as its documentation."—Joe Armstrong, the author of the Erlang programming language

무엇이 좋은 개원 프로젝트입니까?루비를 좋아한다면, Gem Check (truly가 만든) 의 한 곳에서 모든 최선의 실천을 볼 수 있습니다.그러나 언어나 창고를 고려하지 않더라도 모든 OSS 항목에 중요한 것은 문서입니다.

케르시 고타
@ 케일 서해탑

그래서 만들었어.아무도 그것을 사용하고 있지 않다.너는 그 서류들을 잊었니?아하!
2017년 8월 22일 오전 01:08
130
440
모든 개원 항목은 크기를 막론하고 반드시 기록해야 한다.대부분의 경우, 정성들여 작성한 자술 파일만으로도 충분하지만, left-pad을 더 만들 수 있습니다.
그러나 프로젝트가 발전함에 따라 자술한 지원 문서는 작업을 중지합니다."Rails 자술은 확장할 수 없습니다!"라고 말할 수도 있습니다.우리는 옳다.
이것은 우리에게 문제를 가져왔다. "가격 인하 페이지보다 더 신축성이 있는 것이 무엇입니까?"
본문에서 나는 나의 답안을 공유할 것이다.

"멋진 자술" 처음에는 혼란스러웠다

우리가 에 대해 토론을 시작하기 전에, 나는 먼저 당신에게 내가 사용하는 일부 다른 도구를 보여준 다음에 유일한 도구를 확정할 것입니다.

docsify 회사 GitHub Wiki

나의 첫 번째 초과 항목은 이다.나는 일부 문서를 GitHub의 내장wiki로 옮기기 시작했다.만약 우리가 이미 이 공구를 가지고 있다면, 이것이 바로 우리가 가야 할 길이다. 그렇지?응, 꼭 그렇지는 않아.
GitHub wiki가 내장되어 있다는 사실이 유일한 장점이지만 단점 목록은 매우 길어진다.

의 코드와 문서를 독립적으로 업데이트하면 일치하지 않을 수 있습니다.

네트워크 편집기는 아직도 개선해야 할 점이 많다.예를 들어, 이미지를 쉽게 업로드할 수 없습니다(기술적으로는 가능하지만 AnyCable 필요).

교차 인용은 제목을 바꾸어 깨뜨리기 쉽다.영구적인 URL이 있을 수 없습니다.

저기 문서 폴더

모든 위키의 약점을 해결하는 방법 (쌍관어 참조)지금 Repo에 docs 폴더를 만들고 가격 인하 파일로 채워 넣으십시오.브라우저에서 파일을 열면 GitHub에 .md개의 형식이 있는 파일이 표시됩니다.너도 직접 웹 인터페이스에서 내용을 편집할 수 있다!그렇다면 왜wiki기능을 사용해야 합니까?
그래서 우리는 문서 내용을 저장하는 좋은 방법을 찾았다.그런데 사용자 인터페이스/사용자 체험은요?우리의 문서를 더욱 사용자 친화적으로 만들고 싶지 않습니까? (예를 들어 검색 기능 추가)네, 있습니다.
GitHub 구동 문서를 웹 형식으로 변환합니다.

클론wikirepo Jekyll 및 GitHub 페이지

GitHub는 몇 번 클릭하면 이 지원하는 문서 사이트를 만들 수 있습니다.'설정'->'GitHub 페이지'에 들어가서 사이트의 출처를 선택하고 (우리는 docs 폴더를 사용) 당신이 좋아하는 Jekyll 테마를 선택하십시오.

현재 설정 페이지에서 URL을 방문하고 그곳에서 당신의 새로운 문서 사이트를 찾습니다!
Jekyll
불행하게도 GitHub Pages-Jekyll 통합은 유한하다. 특히

방면에서 그렇다.너는 너무 멀리 가면 안 된다.그리고 내가 보기에 페이지의 외관을 사용자 정의하거나 상호작용성을 추가하고 싶다면 Jekyll은 너무 복잡하다.
우리 현대 공구를 좀 봅시다.

도쿠사우루스

내가 시험해 본 첫 번째 현대 문서 생성기는 the available plugins이다.우리는 그것으로 의gem 문서를 구축했다.
Docusaurus
그러나 나는 이 경험이 결코 그렇게 유쾌하지 않다는 것을 인정해야 한다.

은 라이브러리가 React로 구축된 것을 감안하여 더욱 직접적인 맞춤형 옵션이 있기를 바랍니다.그러나 내부 구성 요소에 접근할 수 없습니다. 라이브러리 작성자도 진지하게 조정하기를 원하지 않습니다.

은 내가 처음 사용했을 때 실시간으로 다시 불러오는 것을 지원하지 않았는데, 이것은 로컬 개발에 매우 중요하다 (현재는 Clowne인 것 같다).

은 단독 건축 계단이 필요하다(yarn run build).

그래서 나는 다른 선택을 찾기 시작했고

을 찾았다.

고정적 파일 아카이빙

Docsify는 Jekyll이나 Docusaurus와 다른 방법으로 웹 사이트를 생성합니다. 웹 사이트는 가격 인하 파일을 동적으로 보여 줍니다. 구축 단계가 필요하지 않습니다.
docsify, 심지어 도 지원한다.
docsify docs을 사용하려면 다음과 같이 하십시오.

docs/.nojekyll 파일을 추가하여 Jekyll을 비활성화합니다.

index.html 추가, docsify 로드 및 구성:

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      loadSidebar: true,
      subMaxLevel: 2,
      repo: 'palkan/docs-example',
      basePath: '/docs-example/',
      auto2top: true,
      homepage: 'https://raw.githubusercontent.com/palkan/docs-example/master/README.md'
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-ruby.min.js"></script>
</body>
</html>

그렇습니다!이제 너에게 이런 것이 생겼다.
Server-side rendering
다음과 같은 특정 구성 옵션이 추가되었습니다.

basePath: '/docs-example/은 사이트의 루트 경로(즉 GitHub 페이지에 있는 개인 프로젝트의 리셋 이름)를 정의합니다.

homepage: '...'은 리셋된 자술 파일로 설정됩니다. (기본적으로docsify는 docs/README.md 파일을 사용합니다.)이렇게 하면 두 개의 홈 페이지(GitHub 및 웹)를 동기화할 수 있습니다.

이건 시작일 뿐이야!docsify의 주요 장점 중 하나는 offline mode을 통해 유용한 기능을 추가하는 단순성이다.
검색 기능을 추가하겠습니다.
이 두 줄 코드만 추가하면 됩니다.

 window.$docsify = {
   loadSidebar: true,
   subMaxLevel: 2,
+  search: 'auto',
   repo: 'palkan/docs-example',
   basePath: '/docs-example/',
   auto2top: true,
   homepage: 'https://raw.githubusercontent.com/palkan/docs-example/master/README.md'
   }
 </script>
 <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
 <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
 <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
 <script src="//unpkg.com/prismjs/components/prism-ruby.min.js"></script>

봐라!우리는 우리의 문서를 검색할 수 있다!검색은 클라이언트에서 이루어지며 localStorage에 저장된 인덱스로 지원됩니다.

docsify에 관해서 제가 좋아하는 또 다른 일은 맞춤형 스타일을 만드는 것입니다. 이 라이브러리는 plugins을 사용하기 때문에 자신의 CSS를 구축하지 않고 색과 레이아웃을 변경할 수 있습니다!index.html에서 색상과 글꼴 크기를 변경할 수 있습니다.

<style>
  :root {
    --theme-color: #ff5e5e;
    --theme-color-light: #fd7373;
    --theme-color-dark: #f64242;
    --theme-color-secondary: #ff5e5e;
    --theme-color-secondary-dark: #f64242;
    --theme-color-secondary-light: #fd7373;
    --text-color-base: #363636;
    --text-color-secondary: #646473;
  }
</style>
<body>
  ...
</body>

CSS properties 아닌가요?

The code for the example above could be found on GitHub: palkan/docs-example.

웹 사이트와 awesome을 보고 더 높은 예시를 알아보세요!
AnyCable documentation
보너스*: GitHub에서 편집 기능의 부동 조작 단추를 the corresponding repo에서 찾을 수 있습니다.

솜털로 의사의 건강을 유지하다

본 강좌의 두 번째 부분에서 저는 문서를 건강한 상태로 유지하는 방법을 공유하고 싶습니다.내가 말한 건강 상태는 다음과 같다.

소스 파일(태그)과 코드 예제(Ruby)의 스타일 일치성.

맞춤법이 정확합니다.

개의 유효한 코드 예시 (문법 각도에서)

개의 유효한 링크 (링크가 없으면 4xx/5xx를 가리켜야 함)

이상하게 여기지 않는 것은 개원 도구가 하나 있다.
this gist은 제가 가격 인하 서류 양식을 실시하는 것을 도와줍니다(그리고 과 Markdownlint).
나는 보통 몇 가지 규칙을 사용하지 않는다.

행장(MD013) - 현대 편집기(예를 들어 VS코드)는 포장 긴 줄을 통해 이 문제를 처리할 수 있다.

HTML 세션은 때때로 가격을 내리기에는 부족하다.

이를 위해 프로젝트의 루트 디렉터리에 .mdlrc 파일을 설치했습니다.

rules "~MD013", "~MD033"

루비 문법을 처리하기 위해 a NodeJS version과 이 임무를 위해 작성한 VS Code plugin 플러그인을 사용했습니다.기본 스타일 설정으로 최근에 RuboCop을 사용하기 시작했습니다.
이 설정을 적용하려면 다음이 필요합니다.

설치 standard 및 rubocop-mdgems(gem install standard 및 gem install rubocop-md)

에 .rubocop.yml을 추가하면 다음과 같습니다.

require:
  - standard/cop/semantic_blocks
  - rubocop-md

inherit_gem:
  standard: config/base.yml

Standard/SemanticBlocks:
  Enabled: false

RuboCop을 실행합니다.

맞춤법 검사에는 또 다른 루비 도구-rubocop-md이 있습니다.그것은 유명한 standard포의 포장이다.
기술 용어의 수량으로 인해 첫 번째 실행 중에 Forspell에서 보내는 경고를 많이 볼 수 있습니다.

$ forspell docs/

docs/development/lefthook.md:5: lefthook (suggestions: left hook, left-hook, leftmost)
docs/development/lefthook.md:9: lefthook (suggestions: left hook, left-hook, leftmost)
docs/development/lefthook.md:11: Hombrew (suggestions: Hombre, Hombres, Hombre w)
docs/development/lefthook.md:17: Golang (suggestions: Golan, Golan g, Angolan)

--gen-dictionary 로고를 사용하여 Forspell을 실행하면 이 문제를 쉽게 해결할 수 있습니다. 모든 미지의 단어를 포함하는 forspell.dict 파일을 생성합니다.당신의 눈으로 이 파일을 스캔하고 실제 타자 오류를 삭제하는 것을 잊지 마세요.
마지막으로 문서에 끊어진 링크가 없는지 확인하기 위해 Forspell- Go로 작성된 HTML을 표시하고 표시하는 데 사용되는 링크 관리자를 사용합니다.

$ liche -r docs/

 ERROR    https://githb.com/palkan/anyway_config
                Dialing to the given TCP address timed out

Liche에는 404 응답을 사용하는 URL을 경고하지 않는 등 내가 원하는 기능이 없습니다.그러나 나는 그것이 다른 기존 도구보다 조금 낫다는 것을 발견했다.
이 모든 대들보를 관리하기 위해서 저는 Hunspell을 사용하여 로컬 개발을 하고 CircleCI를 사용하여 요청을 합니다.
다음은 제 lefthook.yml 파일의 내용입니다. 이 파일은 Lefthook의 liche을 저장합니다.

pre-commit:
  commands:
    mdl:
      glob: "**/*.md"
      run: mdl {staged_files}
    liche:
      glob: "**/*.md"
      run: liche -r docs
    forspell:
      glob: "**/*.md"
      run: forspell {staged_files}
    rubocop:
      glob: "**/*.md"
      run: rubocop {staged_files}

CirclCI 구성은 세부적이지만 기본적으로 동일합니다.

version: 2.1

workflows:
  version: 2
  build_and_test:
    jobs:
      - checkout
      - md_lint:
          requires:
            - checkout
      - links_lint:
          requires:
            - checkout
      - spelling:
          requires:
            - checkout
      - rubocop:
          requires:
            - checkout

executors:
  golang:
    docker:
      - image: circleci/golang:1.12.4-stretch
  ruby:
    docker:
      - image: circleci/ruby:2.5-stretch

jobs:
  checkout:
    executor: ruby
    steps:
      - restore_cache:
          keys:
            - project-source-v1-{{ .Branch }}-{{ .Revision }}
            - project-source-v1-{{ .Branch }}
            - project-source-v1
      - checkout
      - save_cache:
          key: project-source-v1-{{ .Branch }}-{{ .Revision }}
          paths:
            - .git
      - persist_to_workspace:
          root: .
          paths: .
  md_lint:
    executor: ruby
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Install mdl
          command: gem install mdl
      - run:
          name: Markdown lint
          command: mdl docs
  links_lint:
    executor: golang
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Install liche
          command: go get -u github.com/raviqqe/liche
      - run:
          name: Check links
          command: liche -r docs
  spelling:
    executor: ruby
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Install hunspell
          command: sudo apt-get install hunspell
      - run:
          name: Install forspell
          command: gem install forspell
      - run:
          name: Check spelling
          command: forspell docs/
  rubocop:
    executor: ruby
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Install standard
          command: gem install standard
      - run:
          name: Install rubocop-md
          command: gem install rubocop-md
      - run:
          name: Check Ruby style
          command: rubocop

전체 예는 Lefthook 환매 협의를 보십시오(PRSconfiguration과 docs.anycable.io 참조).
나는 이 설정을 완성하는 데 시간이 좀 걸렸다.지금 나는 몇 분 안에 새로운 문서 사이트를 만들 수 있다.본고가 매우 유용하다는 것을 발견하고 다음 프로젝트에서 웹 문서를 기반으로 해야 할 때 비슷한 방법을 고려하시기 바랍니다.
승리 문서!
#14에 대한 더 많은 개발 글을 읽으세요!

Reference

이 문제에 관하여(Docsify, Lefthook, friends와 함께 OSS 문서 저장), 우리는 이곳에서 더 많은 자료를 발견하고 링크를 클릭하여 보았다 https://dev.to/evilmartians/keeping-oss-documentation-with-docsify-lefthook-and-friends-11e5

텍스트를 자유롭게 공유하거나 복사할 수 있습니다.하지만 이 문서의 URL은 참조 URL로 남겨 두십시오.

우수한 개발자 콘텐츠 발견에 전념 (Collection and Share based on the CC Protocol.)