Add Table of Contents to pages for viewing via github
まだ誰も着手していません。
評価
- 難易度
- 3/5
- 見積もり時間
- 1〜2日
- 初心者へのやさしさ
- 35/100
- issue の種類
- ドキュメント
- 明瞭さ
- おおむね明確
- 活発さ
- 停滞
- 技術スタック
- markdown
調査の方向性
まず、リポジトリのMarkdownドキュメントページを一覧化し、GitPagesに関する既存のissueの議論を確認します。提案されているdoctocコマンドと、レベル1見出しの後に配置するという提案を評価します。完了の条件は、関連するGitHub表示ページに、ページタイトルを含まないナビゲーション可能な目次があることです。
索引モデルが issue の本文から書いたものです。
説明
Summary: There's a really easy way to do this, and keep it uptodate - this ticket is to explore whether you would accept a pull-request to implement it...
Motivation
Having seen the Table of Contents links on some docs on github, I've found them to be really useful in getting any overview of the topics covered, and then also for really easy navigation.
Examples are:
- https://github.com/catchorg/Catch2/blob/master/docs/assertions.md#top
- https://github.com/approvals/ApprovalTests.cpp/blob/master/doc/Contributing.md#top
I keep coming back to https://github.com/lefticus/cppbestpractices/blob/master/02-Use_the_Tools_Available.md to look for different types of information, and it would save a lot of time and scrolling if users could jump to the section of interest.
Alternatives considered
Searching through the existing issues, I saw #9 which said the solution was to use gitpages,
I downloaded the gitpages PDF, and it doesn't have tables of contents for sections.
And its "Read" feature gives "This site can't be reached" - ERR_CONNECTION_TIMED_OUT - https://lefticus.gitbooks.io/cpp-best-practices/content/
Given how quickly github.com loads Markdown pages, coupled with the convenience of being able to see page histories there and even possibly suggest improvements to the docs, I feel that it's preferable to add Table of Contents to each of the live pages on github.
Possible implementation
For ApprovalTests.cpp, we are using https://github.com/thlorenz/doctoc
It's easy to install:
npm install -g doctoc
Then we run it with this on Windows:
doctoc --title **Contents** .
or this on Unix:
doctoc --title '**Contents**' .
A minor enhancement is to move the generated ToC to after the level-1 heading, so that only level-2 and above headings are included in the ToC.
Consequences
The nice this is that this doesn't require all cppbestpractices contributors to have this tool.
Many edits won't change the ToC, and for those that do, doctoc could be run later by someone who has the tool. (I'd be happy to do that, but it would be better done by someone who has commit-permission on the repo)
- 主要言語
- 言語のデータがありません
- スター
- 8.9k
- フォーク
- 903
- PR マージ指標
- 30日以内にマージされた PR はありません
環境構築
このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
cpp-best-practices/cppbestpractices のほかの issue
-
Broken Link Chapter 2: Use_the_Tools_Available再び着手できるかも @vishesharma20 が 172 日前に担当しましたが、オープン中のプルリクエストはありません。 オープン
難易度 1/5 1時間未満 初心者へのやさしさ 64/100
cpp-best-practices/cppbestpractices#169 · コメント 1 件 ·
-
Broken Link - 11 Further Reading対応中かも このイシューにリンクされたプルリクエストがオープン中、またはマージ済みです。 オープン
難易度 1/5 1時間未満 初心者へのやさしさ 55/100
cpp-best-practices/cppbestpractices#168 · コメント 1 件 ·
-
C++ Practiceオープン
難易度 5/5 1週間以上 初心者へのやさしさ 10/100
-
難易度 1/5 1時間未満 初心者へのやさしさ 35/100
-
難易度 2/5 1〜3時間 初心者へのやさしさ 45/100
cpp-best-practices/cppbestpractices#160 · コメント 1 件 ·
cpp-best-practices/cppbestpractices の issue をすべて見る
似ている issue
-
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
-
[Sync EN] Document the timezone of DateTime(Immutable)::createFromTimestamp() (#6074)対応中かも このイシューにリンクされたプルリクエストがオープン中、またはマージ済みです。 オープンsync-en
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
メンテナーはふだん 1 日以内に返信
-
website
難易度 1/5 1〜3時間 初心者へのやさしさ 88/100
damodharg6/payledger#7 ·
-
area/mobile good first issue help wanted
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
-
難易度 1/5 1時間未満 初心者へのやさしさ 85/100