cpp-best-practices / cpp-best-practices/cppbestpractices

Add Table of Contents to pages for viewing via github

オープン
#103 コメント 1 件 リアクション 1 件 担当者 0 名 GitHub で見る
主要言語
言語のデータがありません
スター
8.8k
フォーク
902
PR マージ指標
30日以内にマージされた PR はありません

説明

_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)

コントリビューションガイド

このリポジトリのコントリビューションガイドは索引されていません

調査の方向性

まず、リポジトリのMarkdownドキュメントページを一覧化し、GitPagesに関する既存のissueの議論を確認します。提案されているdoctocコマンドと、レベル1見出しの後に配置するという提案を評価します。完了の条件は、関連するGitHub表示ページに、ページタイトルを含まないナビゲーション可能な目次があることです。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
markdown
領域
documentation
issue の種類
ドキュメント
難易度
3/5
見積もり時間
1〜2日
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
35/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。