From b3f30d287451e2d41d7c8d5d0558b02c9fac6e71 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:26:08 +0200 Subject: [PATCH 01/20] Test references --- README.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.rst b/README.rst index 0a2189f..864da09 100644 --- a/README.rst +++ b/README.rst @@ -26,6 +26,13 @@ accurate and fully typed. .. _seam_home: https://www.seam.co +Contents +-------- +`Seam ` +Usage `Usage_` +`Usage Usage_` + +.. _Installation: Installation ------------ From 12be803ddb45131c42f572b1990aeab5911d7407 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:28:05 +0200 Subject: [PATCH 02/20] Test --- README.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 864da09..2766678 100644 --- a/README.rst +++ b/README.rst @@ -29,10 +29,11 @@ accurate and fully typed. Contents -------- `Seam ` -Usage `Usage_` +Usage `usage_` `Usage Usage_` .. _Installation: + Installation ------------ @@ -46,6 +47,7 @@ Install it with:: .. _seam: https://pypi.python.org/pypi/seam .. _Python Package Index (PyPI): https://pypi.python.org/ +.. _usage: Usage ----- From 1df9e767ba144b40e239a4458e6cf81f55cd46e7 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:28:49 +0200 Subject: [PATCH 03/20] Test indentation --- README.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/README.rst b/README.rst index 2766678..54b4af6 100644 --- a/README.rst +++ b/README.rst @@ -28,6 +28,7 @@ accurate and fully typed. Contents -------- + `Seam ` Usage `usage_` `Usage Usage_` From 12a5eebef13e6f95c9c616a48f4fd2776e8731b7 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:29:12 +0200 Subject: [PATCH 04/20] Test indentation --- README.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.rst b/README.rst index 54b4af6..58b7440 100644 --- a/README.rst +++ b/README.rst @@ -30,7 +30,9 @@ Contents -------- `Seam ` + Usage `usage_` + `Usage Usage_` .. _Installation: From 6651e7a651f208eca08a84d5d050c11bd6ab675b Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:30:09 +0200 Subject: [PATCH 05/20] Add angle brackets --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 58b7440..331c730 100644 --- a/README.rst +++ b/README.rst @@ -31,9 +31,9 @@ Contents `Seam ` -Usage `usage_` +Usage `` -`Usage Usage_` +`Examples ` .. _Installation: From 7aeb682d2ed9ef2469a4c2c5a7ed332d20184996 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:31:43 +0200 Subject: [PATCH 06/20] Update target --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 331c730..d5cc349 100644 --- a/README.rst +++ b/README.rst @@ -50,7 +50,7 @@ Install it with:: .. _seam: https://pypi.python.org/pypi/seam .. _Python Package Index (PyPI): https://pypi.python.org/ -.. _usage: +.. _usage section: Usage ----- From 4dcdd4164dc870f1e1a23b6bf9ac895fd2e326bf Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:32:56 +0200 Subject: [PATCH 07/20] Trailing underscore --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index d5cc349..1e46d6b 100644 --- a/README.rst +++ b/README.rst @@ -29,11 +29,11 @@ accurate and fully typed. Contents -------- -`Seam ` +`Seam `_ -Usage `` +Usage ``_ -`Examples ` +`Examples `_ .. _Installation: @@ -50,7 +50,7 @@ Install it with:: .. _seam: https://pypi.python.org/pypi/seam .. _Python Package Index (PyPI): https://pypi.python.org/ -.. _usage section: +.. _usage: Usage ----- From 486099a32db16bcb9749c208595a39e8d725c81c Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:34:08 +0200 Subject: [PATCH 08/20] Try lowercase --- README.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/README.rst b/README.rst index 1e46d6b..b36c433 100644 --- a/README.rst +++ b/README.rst @@ -34,6 +34,7 @@ Contents Usage ``_ `Examples `_ +`Examples `_ .. _Installation: From d8975b663abb857bc18310a26c8194574afff299 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:38:01 +0200 Subject: [PATCH 09/20] Try nested contents --- README.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index b36c433..f9eee18 100644 --- a/README.rst +++ b/README.rst @@ -29,14 +29,13 @@ accurate and fully typed. Contents -------- -`Seam `_ +`Installation `_ -Usage ``_ +`Usage `_ -`Examples `_ -`Examples `_ + `Examples `_ -.. _Installation: + `List devices `_ Installation ------------ From 2f2740160b6cdfa4c270ca014ef05fb31aa67611 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:40:25 +0200 Subject: [PATCH 10/20] Try unordered list --- README.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index f9eee18..d241467 100644 --- a/README.rst +++ b/README.rst @@ -29,13 +29,13 @@ accurate and fully typed. Contents -------- -`Installation `_ +* `Installation `_ -`Usage `_ +* `Usage `_ - `Examples `_ + * `Examples `_ - `List devices `_ + * `List devices `_ Installation ------------ @@ -50,7 +50,6 @@ Install it with:: .. _seam: https://pypi.python.org/pypi/seam .. _Python Package Index (PyPI): https://pypi.python.org/ -.. _usage: Usage ----- From a8d20172f6b1fd6b940b4e37cf6d6b86b91d7045 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:42:08 +0200 Subject: [PATCH 11/20] Test without new line --- README.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/README.rst b/README.rst index d241467..3562887 100644 --- a/README.rst +++ b/README.rst @@ -36,6 +36,7 @@ Contents * `Examples `_ * `List devices `_ + * `Unlock a door `_ Installation ------------ From 9ea9c67bdd9bb89c223f84422bb8a0c95316f9eb Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:43:48 +0200 Subject: [PATCH 12/20] Add more contents --- README.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 3562887..0e7fa0b 100644 --- a/README.rst +++ b/README.rst @@ -30,13 +30,12 @@ Contents -------- * `Installation `_ - * `Usage `_ - * `Examples `_ - * `List devices `_ * `Unlock a door `_ + * `Authentication Method `_ + * `API Key `_ Installation ------------ From 954455c126512355b30dc7f77f2a9fba330ae9e0 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 12:44:42 +0200 Subject: [PATCH 13/20] Add new lines --- README.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.rst b/README.rst index 0e7fa0b..c948ac0 100644 --- a/README.rst +++ b/README.rst @@ -30,11 +30,17 @@ Contents -------- * `Installation `_ + * `Usage `_ + * `Examples `_ + * `List devices `_ + * `Unlock a door `_ + * `Authentication Method `_ + * `API Key `_ Installation From 09bfb506e7ec96ff2c507c5f4a7e9efd40d624d4 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 13:38:01 +0200 Subject: [PATCH 14/20] Add script for generating TOC --- generate-readme-toc.js | 79 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 generate-readme-toc.js diff --git a/generate-readme-toc.js b/generate-readme-toc.js new file mode 100644 index 0000000..86b3d0f --- /dev/null +++ b/generate-readme-toc.js @@ -0,0 +1,79 @@ +import fs from 'fs/promises' + +async function generateTOC(content) { + const lines = content.split('\n') + const headings = [] + let contentsIndex = -1 + let parsingHeadings = false + + for (let i = 0; i < lines.length; i++) { + const line = lines[i].trim() + const nextLine = lines[i + 1]?.trim() || '' + + if (line === 'Contents' && nextLine.startsWith('--------')) { + contentsIndex = i + parsingHeadings = true + i++ // Skip the underline + continue + } + + if (parsingHeadings && nextLine && nextLine.match(/^[-~^]+$/)) { + const level = + nextLine[0] === '-' + ? 1 + : nextLine[0] === '~' + ? 2 + : nextLine[0] === '^' + ? 3 + : 0 + if (level > 0 && line) { + headings.push({ text: line, level }) + } + i++ // Skip the underline + } + } + + const toc = [''] // Start with an empty line after the "Contents" section + headings.forEach((heading) => { + const indent = ' '.repeat(heading.level - 1) + const link = heading.text.replace(/ /g, '_') + toc.push(`${indent}* \`${heading.text} <${link}_>\`_`) + toc.push('') // Add a newline after each item, including the last one + }) + + return { toc, contentsIndex } +} + +async function updateReadme() { + try { + const content = await fs.readFile('README.rst', 'utf8') + const { toc, contentsIndex } = await generateTOC(content) + + if (contentsIndex === -1) { + console.error('Contents heading not found in the file.') + process.exit(1) + } + + const lines = content.split('\n') + const contentStartIndex = lines.findIndex( + (line, index) => + index > contentsIndex + 2 && + !line.trim().startsWith('*') && + line.trim() !== '', + ) + + const newContent = [ + ...lines.slice(0, contentsIndex + 2), // Include "Contents" and its underline + ...toc, + ...lines.slice(contentStartIndex), + ].join('\n') + + await fs.writeFile('README.rst', newContent) + console.log('Table of Contents has been updated in README.rst') + } catch (error) { + console.error('Error processing file:', error) + process.exit(1) + } +} + +updateReadme() From e99931f8c848d2d1728acc92b2354e26ee63f209 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 13:38:16 +0200 Subject: [PATCH 15/20] Generate TOC --- README.rst | 46 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 42 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index c948ac0..21c9c1e 100644 --- a/README.rst +++ b/README.rst @@ -35,13 +35,51 @@ Contents * `Examples `_ - * `List devices `_ + * `List devices `_ - * `Unlock a door `_ + * `Unlock a door `_ - * `Authentication Method `_ + * `Authentication Method `_ - * `API Key `_ + * `API Key `_ + + * `Personal Access Token `_ + + * `Action Attempts `_ + + * `Interacting with Multiple Workspaces `_ + + * `Webhooks `_ + + * `Advanced Usage `_ + + * `Setting the endpoint `_ + +* `Development and Testing `_ + + * `Quickstart `_ + + * `Source Code `_ + + * `Requirements `_ + + * `Tests `_ + + * `Publishing `_ + + * `Automatic `_ + + * `Manual `_ + +* `GitHub Actions `_ + + * `Secrets for Optional GitHub Actions `_ + +* `Contributing `_ + +* `License `_ + +* `Warranty `_ Installation ------------ From b63796e04604cf5e371b50e244e9b4340531647c Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 13:39:32 +0200 Subject: [PATCH 16/20] Add generate TOC to postgenerate script --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index cecaa6c..cb550c1 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "type": "module", "scripts": { "generate": "node generate-routes.js", - "postgenerate": "make format", + "postgenerate": "node generate-readme-toc.js && make format", "format": "prettier --write --ignore-path .gitignore .", "start": "fake-seam-connect --seed" }, From a55259948c0f76496d8b39675042b4bcf75bcd6f Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 13:41:35 +0200 Subject: [PATCH 17/20] Fix the hyperlinks produced by the generate TOC script --- README.rst | 26 +++++++++++++------------- generate-readme-toc.js | 3 +-- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/README.rst b/README.rst index 21c9c1e..498c157 100644 --- a/README.rst +++ b/README.rst @@ -35,31 +35,31 @@ Contents * `Examples `_ - * `List devices `_ + * `List devices `_ - * `Unlock a door `_ + * `Unlock a door `_ - * `Authentication Method `_ + * `Authentication Method `_ - * `API Key `_ + * `API Key `_ - * `Personal Access Token `_ + * `Personal Access Token `_ - * `Action Attempts `_ + * `Action Attempts `_ - * `Interacting with Multiple Workspaces `_ + * `Interacting with Multiple Workspaces `_ * `Webhooks `_ - * `Advanced Usage `_ + * `Advanced Usage `_ - * `Setting the endpoint `_ + * `Setting the endpoint `_ -* `Development and Testing `_ +* `Development and Testing `_ * `Quickstart `_ - * `Source Code `_ + * `Source Code `_ * `Requirements `_ @@ -71,9 +71,9 @@ Contents * `Manual `_ -* `GitHub Actions `_ +* `GitHub Actions `_ - * `Secrets for Optional GitHub Actions `_ + * `Secrets for Optional GitHub Actions `_ * `Contributing `_ diff --git a/generate-readme-toc.js b/generate-readme-toc.js index 86b3d0f..70681b9 100644 --- a/generate-readme-toc.js +++ b/generate-readme-toc.js @@ -36,8 +36,7 @@ async function generateTOC(content) { const toc = [''] // Start with an empty line after the "Contents" section headings.forEach((heading) => { const indent = ' '.repeat(heading.level - 1) - const link = heading.text.replace(/ /g, '_') - toc.push(`${indent}* \`${heading.text} <${link}_>\`_`) + toc.push(`${indent}* \`${heading.text} <${heading.text}_>\`_`) toc.push('') // Add a newline after each item, including the last one }) From 4f3c9a121ff67ff16beae43e5555c200fedd5402 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 14:57:44 +0200 Subject: [PATCH 18/20] Improve script's readability --- generate-readme-toc.js | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/generate-readme-toc.js b/generate-readme-toc.js index 70681b9..7386671 100644 --- a/generate-readme-toc.js +++ b/generate-readme-toc.js @@ -1,9 +1,9 @@ import fs from 'fs/promises' -async function generateTOC(content) { +async function generateTableOfContents(content) { const lines = content.split('\n') const headings = [] - let contentsIndex = -1 + let contentsHeadingIndex = -1 let parsingHeadings = false for (let i = 0; i < lines.length; i++) { @@ -11,8 +11,8 @@ async function generateTOC(content) { const nextLine = lines[i + 1]?.trim() || '' if (line === 'Contents' && nextLine.startsWith('--------')) { - contentsIndex = i - parsingHeadings = true + contentsHeadingIndex = i + parsingHeadings = true // Start parsing headings after the "Contents" section i++ // Skip the underline continue } @@ -33,38 +33,39 @@ async function generateTOC(content) { } } + // Generate table of contents const toc = [''] // Start with an empty line after the "Contents" section headings.forEach((heading) => { const indent = ' '.repeat(heading.level - 1) toc.push(`${indent}* \`${heading.text} <${heading.text}_>\`_`) - toc.push('') // Add a newline after each item, including the last one + toc.push('') // Add a newline after each item }) - return { toc, contentsIndex } + return { toc, contentsHeadingIndex } } async function updateReadme() { try { const content = await fs.readFile('README.rst', 'utf8') - const { toc, contentsIndex } = await generateTOC(content) + const { toc, contentsHeadingIndex } = await generateTableOfContents(content) - if (contentsIndex === -1) { - console.error('Contents heading not found in the file.') + if (contentsHeadingIndex === -1) { + console.error('Contents heading not found in the README.') process.exit(1) } const lines = content.split('\n') - const contentStartIndex = lines.findIndex( + const tocTableEndIndex = lines.findIndex( (line, index) => - index > contentsIndex + 2 && + index > contentsHeadingIndex + 2 && !line.trim().startsWith('*') && line.trim() !== '', ) const newContent = [ - ...lines.slice(0, contentsIndex + 2), // Include "Contents" and its underline + ...lines.slice(0, contentsHeadingIndex + 2), // Include readme content before "Contents" heading, the heading itself and its underline ...toc, - ...lines.slice(contentStartIndex), + ...lines.slice(tocTableEndIndex), // Include all content after the previous TOC ].join('\n') await fs.writeFile('README.rst', newContent) From 203a0229c9f556b56702472cee8e5bd942588398 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <10balian10@gmail.com> Date: Fri, 2 Aug 2024 15:06:31 +0200 Subject: [PATCH 19/20] More readability improvements --- generate-readme-toc.js | 67 +++++++++++++++++++++++++----------------- 1 file changed, 40 insertions(+), 27 deletions(-) diff --git a/generate-readme-toc.js b/generate-readme-toc.js index 7386671..2a0968d 100644 --- a/generate-readme-toc.js +++ b/generate-readme-toc.js @@ -1,5 +1,15 @@ import fs from 'fs/promises' +const README_FILE = 'README.rst' +const CONTENTS_HEADING = 'Contents' +const CONTENTS_UNDERLINE = '--------' +const TOC_INDENT_LEVELS = { + '-': 1, + '~': 2, + '^': 3, +} +const HEADING_UNDERLINE_REGEX = /^[-~^]+$/ + async function generateTableOfContents(content) { const lines = content.split('\n') const headings = [] @@ -10,68 +20,71 @@ async function generateTableOfContents(content) { const line = lines[i].trim() const nextLine = lines[i + 1]?.trim() || '' - if (line === 'Contents' && nextLine.startsWith('--------')) { + if (line === CONTENTS_HEADING && nextLine.startsWith(CONTENTS_UNDERLINE)) { contentsHeadingIndex = i parsingHeadings = true // Start parsing headings after the "Contents" section i++ // Skip the underline continue } - if (parsingHeadings && nextLine && nextLine.match(/^[-~^]+$/)) { - const level = - nextLine[0] === '-' - ? 1 - : nextLine[0] === '~' - ? 2 - : nextLine[0] === '^' - ? 3 - : 0 + if ( + parsingHeadings && + nextLine && + nextLine.match(HEADING_UNDERLINE_REGEX) + ) { + const level = TOC_INDENT_LEVELS[nextLine[0]] || 0 + if (level > 0 && line) { headings.push({ text: line, level }) } - i++ // Skip the underline + + i++ } } // Generate table of contents - const toc = [''] // Start with an empty line after the "Contents" section + const toc = [''] headings.forEach((heading) => { const indent = ' '.repeat(heading.level - 1) + toc.push(`${indent}* \`${heading.text} <${heading.text}_>\`_`) - toc.push('') // Add a newline after each item + toc.push('') }) return { toc, contentsHeadingIndex } } +function findTocEndIndex(lines, startIndex) { + return lines.findIndex( + (line, index) => + index > startIndex + 2 && + !line.trim().startsWith('*') && + line.trim() !== '', + ) +} + async function updateReadme() { try { - const content = await fs.readFile('README.rst', 'utf8') + const content = await fs.readFile(README_FILE, 'utf8') const { toc, contentsHeadingIndex } = await generateTableOfContents(content) if (contentsHeadingIndex === -1) { - console.error('Contents heading not found in the README.') - process.exit(1) + throw new Error('Contents heading not found in the README.') } const lines = content.split('\n') - const tocTableEndIndex = lines.findIndex( - (line, index) => - index > contentsHeadingIndex + 2 && - !line.trim().startsWith('*') && - line.trim() !== '', - ) + const tocEndIndex = findTocEndIndex(lines, contentsHeadingIndex) const newContent = [ - ...lines.slice(0, contentsHeadingIndex + 2), // Include readme content before "Contents" heading, the heading itself and its underline + ...lines.slice(0, contentsHeadingIndex + 2), // Include content before "Contents" heading, the heading itself and its underline ...toc, - ...lines.slice(tocTableEndIndex), // Include all content after the previous TOC + ...lines.slice(tocEndIndex), ].join('\n') - await fs.writeFile('README.rst', newContent) - console.log('Table of Contents has been updated in README.rst') + await fs.writeFile(README_FILE, newContent) + console.log(`Table of Contents has been updated in ${README_FILE}`) } catch (error) { - console.error('Error processing file:', error) + console.error('Error updating README:', error.message) process.exit(1) } } From 87400e165ab31beb4f2ebc7e5e092f7c48c1f667 Mon Sep 17 00:00:00 2001 From: Andrii Balitskyi <84702959+andrii-balitskyi@users.noreply.github.com> Date: Fri, 2 Aug 2024 16:59:04 +0200 Subject: [PATCH 20/20] Update package.json Co-authored-by: Evan Sosenko --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index cb550c1..a0560bb 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,8 @@ "type": "module", "scripts": { "generate": "node generate-routes.js", - "postgenerate": "node generate-readme-toc.js && make format", + "pregenerate": "node generate-readme-toc.js", + "postgenerate": "make format", "format": "prettier --write --ignore-path .gitignore .", "start": "fake-seam-connect --seed" },