break up the publishing chapter into two separate chapters

tomjoht · Sep 2, 2023 · 3ddf7e2 · 3ddf7e2
1 parent 911223b
commit 3ddf7e2
Show file tree

Hide file tree

Showing 19 changed files with 53 additions and 50 deletions.
diff --git a/_data/docapis.yml b/_data/docapis.yml
@@ -359,7 +359,7 @@ folders:
   - title: "More about Markdown"
     jurl: /learnapidoc/pubapis_markdown.html
 
-  - title: "Version control systems (e.g., Git)"
+  - title: "Version control systems"
     jurl: /learnapidoc/pubapis_version_control.html
 
   - title: "Static site generators"
@@ -375,7 +375,7 @@ folders:
     jurl: /learnapidoc/pubapis_which_tool_to_choose.html
 
 - title: "Chapter 11: Publishing tools"
-  landing: /learnapidoc/publishingapis.html
+  landing: /learnapidoc/publishingtools.html
   section: eleven
   folderitems:
 

diff --git a/_data/glossary.yml b/_data/glossary.yml
@@ -4,7 +4,7 @@ agile_testing:
 
 api: 
   term: API (Application Programming Interface)
-  def: "A set of definitions, protocols, and tools for building software applications. APIs allow different systems to communicate with each other."
+  def: "A set of definitions, protocols, and tools for building software applications. APIs allow different systems to interact with each other programmatically. This course focuses mostly on REST APIs, but there are also language-based APIs such as Java, C++, Python, and more. I refer to these as native library APIs."
 
 api_blueprint: 
   term: API Blueprint

diff --git a/_data/topnav.yml b/_data/topnav.yml
@@ -47,25 +47,28 @@ topnav_dropdowns:
         - title: "Chapter 10: Publishing API docs"
           url: /learnapidoc/publishingapis.html
 
-        - title: "Chapter 11: Thriving in the API doc space"
+        - title: "Chapter 11: Publishing tools and workflows"
+          url: /learnapidoc/publishingtools.html
+
+        - title: "Chapter 12: Thriving in the API doc space"
           url: /learnapidoc/jobapis.html
 
-        - title: "Chapter 12: Native library APIs"
+        - title: "Chapter 13: Native library APIs"
           url: /learnapidoc/nativelibraryapis.html
 
-        - title: "Chapter 13: Processes and methodology"
+        - title: "Chapter 14: Processes and methodology"
           url: /learnapidoc/docapis_managing_doc_processes.html
 
-        - title: "Chapter 14: Metrics and measurement"
+        - title: "Chapter 15: Metrics and measurement"
           url: /learnapidoc/docapis_metrics_and_measurement.html
 
-        - title: "Chapter 15: AI tools and API documentation"
+        - title: "Chapter 16: AI tools and API documentation"
           url: /learnapidoc/ai.html
 
-        - title: "Chapter 16: Glossary"
+        - title: "Chapter 17: Glossary"
           url: /learnapidoc/glossary_overview.html
 
-        - title: "Chapter 17: Additional resources"
+        - title: "Chapter 18: Additional resources"
           url: /learnapidoc/resources.html
 
     - title: Downloads

diff --git a/_docs/additional_resources/resources.md b/_docs/additional_resources/resources.md
@@ -1,5 +1,5 @@
 ---
-title: "Chapter 17: Additional resources"
+title: "Chapter 18: Additional resources"
 permalink: learnapidoc/resources.html
 course: "Documenting REST APIs"
 sidebar: docapis

diff --git a/_docs/ai/ai.md b/_docs/ai/ai.md
@@ -1,5 +1,5 @@
 ---
-title: "Chapter 15: AI tools and API documentation"
+title: "Chapter 16: AI tools and API documentation"
 permalink: learnapidoc/ai.html
 keywords:
 course: "Documenting REST APIs"

diff --git a/_docs/glossary/glossary.md b/_docs/glossary/glossary.md
@@ -1,5 +1,5 @@
 ---
-title: Glossary
+title: "Chapter 17: Glossary"
 permalink: learnapidoc/glossary.html
 keywords:
 course: "Documenting REST APIs"

diff --git a/_docs/glossary/glossary_groups.md b/_docs/glossary/glossary_groups.md
@@ -170,12 +170,6 @@ api_tools_and_platforms:
 {% assign glossaryFile = site.data.glossary %}
 {% assign counter = 0 %}
 
-{% if site.format == "print" %}
-*Note: This content doesn't embed well in print because it contains JavaScript. Please go to [https://idratherbewriting.com/learnapidoc/api-glossary-groups.html] to view the content.*
-{% endif %}
-
-{% if site.format == "web" %}
-
 ## Basic terms
 
 {% include glossary_group.html group_name="Basic terms" group_code="basic_terms" %}
@@ -236,8 +230,6 @@ api_tools_and_platforms:
 
 {% include glossary_group.html group_name="API tools and platform terms" group_code="api_tools_and_platforms" %}
 
-{% endif %}
-
 {% include random_ad2.html %}
 {% include random_ad4.html %}
 {% include random_ad3.html %}

diff --git a/_docs/metrics_and_measurement/docapis_metrics_and_measurement.md b/_docs/metrics_and_measurement/docapis_metrics_and_measurement.md
@@ -1,5 +1,5 @@
 ---
-title: "Chapter 13: Metrics and measurement"
+title: "Chapter 15: Metrics and measurement"
 permalink: /learnapidoc/docapis_metrics_and_measurement.html
 course: "Documenting REST APIs"
 weight: 13.0

diff --git a/_docs/native_library_apis/nativelibraryapis.md b/_docs/native_library_apis/nativelibraryapis.md
@@ -1,5 +1,5 @@
 ---
-title: "Chapter 12: Native library APIs"
+title: "Chapter 13: Native library APIs"
 permalink: learnapidoc/nativelibraryapis.html
 sidebar: docapis
 path1: learnapidoc/nativelibraryapis.html

diff --git a/_docs/processes_and_methodology/docapis_managing_doc_processes.md b/_docs/processes_and_methodology/docapis_managing_doc_processes.md
@@ -1,5 +1,5 @@
 ---
-title: "Chapter 8: Documentation processes and methodology"
+title: "Chapter 14: Documentation processes and methodology"
 permalink: learnapidoc/docapis_managing_doc_processes.html
 course: "Documenting REST APIs"
 weight: 12.0

diff --git a/_docs/publishing_tools/docapis_faq_tools.md b/_docs/publishing_tools/docapis_faq_tools.md
@@ -5,7 +5,7 @@ course: "Documenting REST APIs"
 sidebar: docapis
 path1: learnapidoc/publishingtools.html
 section: publishingtools
-weight: 9.98
+weight: 9.99
 last-modified: 2020-06-13
 ---
 

diff --git a/_docs/publishing_tools/pubapis_blobr.md b/_docs/publishing_tools/pubapis_blobr.md
@@ -3,7 +3,7 @@ title: "Blobr: An API portal that arranges your API's use cases as individual pr
 permalink: learnapidoc/pubapis_blobr.html
 course: "Documenting REST APIs"
 sidebar: docapis
-weight: 9.96
+weight: 9.97
 path1: learnapidoc/publishingtools.html
 section: publishingtools
 last-modified: 2022-06-01

diff --git a/_docs/publishing_tools/pubapis_oxygenxml.md b/_docs/publishing_tools/pubapis_oxygenxml.md
@@ -3,7 +3,7 @@ title: "Using Oxygen XML with docs-as-code workflows"
 permalink: learnapidoc/pubapis_oxygenxml.html
 course: "Documenting REST APIs"
 sidebar: docapis
-weight: 9.94
+weight: 9.96
 path1: learnapidoc/publishingtools.html
 section: publishingtools
 last-modified: 2021-10-13

diff --git a/_docs/publishing_tools/pubapis_switching_to_docs_as_code.md b/_docs/publishing_tools/pubapis_switching_to_docs_as_code.md
@@ -3,7 +3,7 @@ title: "Case study: Switching tools to docs-as-code"
 permalink: learnapidoc/pubapis_switching_to_docs_as_code.html
 course: "Documenting REST APIs"
 sidebar: docapis
-weight: 9.97
+weight: 9.98
 section: publishingapis
 path1: learnapidoc/publishingapis.html
 redirect_from:

diff --git a/_docs/publishing_tools/publishingtools.md b/_docs/publishing_tools/publishingtools.md
@@ -1,5 +1,5 @@
 ---
-title: "Chapter 11: Publishing tools"
+title: "Chapter 11: Publishing tools and workflows"
 permalink: learnapidoc/publishingtools.html
 sidebar: docapis
 path1: learnapidoc/publishingtools.html
@@ -11,6 +11,6 @@ last-modified: 2023-09-01
 
 {% include coffeeshopbook.html %}
 
-This section focuses on various publishing tools and tutorials related to those tools.
+This section focuses on various publishing tools and tutorials related to those tools. The chapter continues similar themes of publishing from the previous chapter but dives into the details of several tools, a publishing workflow, case study, and more.
 
 {% include minitoc.html %}
diff --git a/_docs/thriving_in_the_api_doc_space/jobapis.md b/_docs/thriving_in_the_api_doc_space/jobapis.md
@@ -1,5 +1,5 @@
 ---
-title: "Chapter 11: Thriving in the API doc space"
+title: "Chapter 12: Thriving in the API doc space"
 permalink: learnapidoc/jobapis.html
 sidebar: docapis
 path1: learnapidoc/jobapis.html

diff --git a/_includes/coffee_button.html b/_includes/coffee_button.html
@@ -1,3 +1,5 @@
+{% comment %}
 {% if site.format == "web" %}
 <style>.bmc-button img{height: 34px !important;width: 35px !important;margin-bottom: 1px !important;margin-top: -1px !important;box-shadow: none !important;border: none !important;vertical-align: middle !important;}.bmc-button{padding: 7px 15px 7px 10px !important;line-height: 35px !important;height:51px !important;text-decoration: none !important;display:inline-flex !important;color:#000000 !important;background-color:#FFFFFF !important;border-radius: 5px !important;border: 1px solid transparent !important;padding: 7px 15px 7px 10px !important;font-size: 28px !important;letter-spacing:0.6px !important;box-shadow: 0px 1px 2px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 1px 2px 2px rgba(190, 190, 190, 0.5) !important;margin: 0 auto !important;font-family:'Cookie', cursive !important;-webkit-box-sizing: border-box !important;box-sizing: border-box !important;}.bmc-button:hover, .bmc-button:active, .bmc-button:focus {-webkit-box-shadow: 0px 1px 2px 2px rgba(190, 190, 190, 0.5) !important;text-decoration: none !important;box-shadow: 0px 1px 2px 2px rgba(190, 190, 190, 0.5) !important;opacity: 0.85 !important;color:#000000 !important;}</style><link href="https://fonts.googleapis.com/css?family=Cookie" rel="stylesheet"><a class="bmc-button" target="_blank" href="https://www.buymeacoffee.com/learnapidoc"><img src="https://cdn.buymeacoffee.com/buttons/bmc-new-btn-logo.svg" alt="Buy me a coffee"><span style="margin-left:5px;font-size:28px !important;">Buy me a coffee</span></a>
 {% endif %}
+{% endcomment %}
diff --git a/_includes/glossary_group.html b/_includes/glossary_group.html
@@ -1,11 +1,15 @@
-
+{% if site.format == "web" %}
 {% assign counter = counter | plus: 1 %}
 <button type="button" class="btn btn-info" data-toggle="collapse" data-target="#demo{{ counter }}">{{include.group_name}} &raquo;</button>
 <div id="demo{{ counter }}" class="collapse defs">
+{% endif %}
+<p>These terms are all related to {{include.group_name}}.</p>
 <dl>
 {% for entry in page.[include.group_code] %}
 <dt><a id="{{entry}}"></a>{{glossaryFile[entry].term}}</dt>
 <dd markdown="span">{{glossaryFile[entry].def}}</dd>
 {% endfor %}
 </dl>
-</div>
+{% if site.format == "web" %}
+</div>
+{% endif %}
diff --git a/pdf_build_docapis_all.sh b/pdf_build_docapis_all.sh
@@ -8,24 +8,26 @@ LOCATION="/Users/tomjoht/projects/idratherbewriting/pdf"
 
 echo "now splitting the comprehensive PDF up into individual chapters"
 pdftk $LOCATION/docapis_all_chapters.pdf cat 1-8 output $LOCATION/frontmatter.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 9-71 output $LOCATION/chapter1_introduction_to_rest_apis.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 72-121 output $LOCATION/chapter2_using_an_api_like_a_developer.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 122-186 output $LOCATION/chapter3_documenting_api_endpoints.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 187-278 output $LOCATION/chapter4_openapi_spec_and_generated_reference_docs.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 279-349 output $LOCATION/chapter5_step_by_step_openapi_code_tutorial.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 350-365 output $LOCATION/chapter6_testing_api_docs.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 366-439 output $LOCATION/chapter7_conceptual_topics_in_api_docs.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 440-508 output $LOCATION/chapter8_code_tutorials.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 509-537 output $LOCATION/chapter9_the_writing_process.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 538-666 output $LOCATION/chapter10_publishing_api_docs.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 667-698 output $LOCATION/chapter11_thriving_in_the_api_doc_space.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 699-734 output $LOCATION/chapter12_native_library_apis.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 735-807 output $LOCATION/chapter13_processes_and_methodology.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 808-833 output $LOCATION/chapter14_metrics_and_measurement.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 834-899 output $LOCATION/chapter15_ai_and_api_docs.pdf
-pdftk $LOCATION/docapis_all_chapters.pdf cat 900-963 output $LOCATION/chapter16_additional_resources.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 9-62 output $LOCATION/chapter1_introduction_to_rest_apis.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 63-112 output $LOCATION/chapter2_using_an_api_like_a_developer.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 113-173 output $LOCATION/chapter3_documenting_api_endpoints.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 174-265 output $LOCATION/chapter4_openapi_spec_and_generated_reference_docs.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 266-336 output $LOCATION/chapter5_step_by_step_openapi_code_tutorial.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 337-352 output $LOCATION/chapter6_testing_api_docs.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 353-425 output $LOCATION/chapter7_conceptual_topics_in_api_docs.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 427-495 output $LOCATION/chapter8_code_tutorials.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 496-524 output $LOCATION/chapter9_the_writing_process.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 525-588 output $LOCATION/chapter10_publishing_api_docs.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 589-654 output $LOCATION/chapter11_publishing_tools.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 655-686 output $LOCATION/chapter12_thriving_in_the_api_doc_space.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 687-722 output $LOCATION/chapter13_native_library_apis.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 723-795 output $LOCATION/chapter14_processes_and_methodology.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 796-821 output $LOCATION/chapter15_metrics_and_measurement.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 822-887 output $LOCATION/chapter16_ai_and_api_docs.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 888-917 output $LOCATION/chapter17_glossary.pdf
+pdftk $LOCATION/docapis_all_chapters.pdf cat 918-981 output $LOCATION/chapter18_additional_resources.pdf
 
 echo "Now zipping everything up"
-zip pdf/docapis.zip pdf/readme.txt pdf/docapis_all_chapters.pdf pdf/frontmatter.pdf pdf/chapter1_introduction_to_rest_apis.pdf pdf/chapter2_using_an_api_like_a_developer.pdf pdf/chapter3_documenting_api_endpoints.pdf pdf/chapter4_openapi_spec_and_generated_reference_docs.pdf pdf/chapter5_step_by_step_openapi_code_tutorial.pdf pdf/chapter6_testing_api_docs.pdf pdf/chapter7_conceptual_topics_in_api_docs.pdf pdf/chapter8_code_tutorials.pdf pdf/chapter9_the_writing_process.pdf pdf/chapter10_publishing_api_docs.pdf pdf/chapter11_thriving_in_the_api_doc_space.pdf pdf/chapter12_native_library_apis.pdf pdf/chapter13_processes_and_methodology.pdf pdf/chapter14_metrics_and_measurement.pdf pdf/chapter15_ai_and_api_docs.pdf pdf/chapter16_additional_resources.pdf
+zip pdf/docapis.zip pdf/readme.txt pdf/docapis_all_chapters.pdf pdf/frontmatter.pdf pdf/chapter1_introduction_to_rest_apis.pdf pdf/chapter2_using_an_api_like_a_developer.pdf pdf/chapter3_documenting_api_endpoints.pdf pdf/chapter4_openapi_spec_and_generated_reference_docs.pdf pdf/chapter5_step_by_step_openapi_code_tutorial.pdf pdf/chapter6_testing_api_docs.pdf pdf/chapter7_conceptual_topics_in_api_docs.pdf pdf/chapter8_code_tutorials.pdf pdf/chapter9_the_writing_process.pdf pdf/chapter10_publishing_api_docs.pdf pdf/chapter11_publishing_tools.pdf pdf/chapter12_thriving_in_the_api_doc_space.pdf pdf/chapter13_native_library_apis.pdf pdf/chapter14_processes_and_methodology.pdf pdf/chapter15_metrics_and_measurement.pdf pdf/chapter16_ai_and_api_docs.pdf pdf/chapter17_glossary.pdf pdf/chapter18_additional_resources.pdf
 
 echo "All done. Now run ./pdf_upload_docapis.sh"