[PATCH 0/1] [Outreachy] doc: remove api-index

[PATCH 0/1] [Outreachy] doc: remove api-index

[Heba Waly via GitGitGadget]

Remove both api-index.txt and api-index-skel.txt as the API documentation is
being moved to the header files, so the index is not needed anymore because
the doc files (Documentation/technical/api-*.txt) will be gone.

Make changes to Documentation/Makefile accordingly.

Signed-off-by: Heba Waly heba.waly@gmail.com [heba.waly@gmail.com]

Heba Waly (1):
  api-index: remove api doc index files

 Documentation/Makefile                     | 11 +++------
 Documentation/git.txt                      |  3 ---
 Documentation/technical/.gitignore         |  1 -
 Documentation/technical/api-index-skel.txt | 13 ----------
 Documentation/technical/api-index.sh       | 28 ----------------------
 5 files changed, 3 insertions(+), 53 deletions(-)
 delete mode 100644 Documentation/technical/.gitignore
 delete mode 100644 Documentation/technical/api-index-skel.txt
 delete mode 100755 Documentation/technical/api-index.sh


base-commit: da72936f544fec5a335e66432610e4cef4430991
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-456%2FHebaWaly%2Fremove-api-index-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-456/HebaWaly/remove-api-index-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/456
-- 
gitgitgadget

[PATCH 1/1] api-index: remove api doc index files

[Heba Waly via GitGitGadget]

From: Heba Waly <heba.waly@gmail.com>

Remove both api-index.txt and api-index-skel.txt as the API documentation
is being moved to the header files, so the index is not needed anymore
because the doc files (Documentation/technical/api-*.txt) will be gone.

Make changes to Documentation/Makefile accordingly.

Signed-off-by: Heba Waly <heba.waly@gmail.com>
---
 Documentation/Makefile                     | 11 +++------
 Documentation/git.txt                      |  3 ---
 Documentation/technical/.gitignore         |  1 -
 Documentation/technical/api-index-skel.txt | 13 ----------
 Documentation/technical/api-index.sh       | 28 ----------------------
 5 files changed, 3 insertions(+), 53 deletions(-)
 delete mode 100644 Documentation/technical/.gitignore
 delete mode 100644 Documentation/technical/api-index-skel.txt
 delete mode 100755 Documentation/technical/api-index.sh

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 06d85ad958..0788dd12e8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -73,7 +73,7 @@ SP_ARTICLES += howto/rebuild-from-update-hook
 SP_ARTICLES += howto/rebase-from-internal-branch
 SP_ARTICLES += howto/keep-canonical-history-correct
 SP_ARTICLES += howto/maintain-git
-API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
+API_DOCS = $(patsubst %.txt,%,$(wildcard technical/api-*.txt))
 SP_ARTICLES += $(API_DOCS)
 
 TECH_DOCS += MyFirstContribution
@@ -96,7 +96,6 @@ TECH_DOCS += technical/shallow
 TECH_DOCS += technical/signature-format
 TECH_DOCS += technical/trivial-merge
 SP_ARTICLES += $(TECH_DOCS)
-SP_ARTICLES += technical/api-index
 
 ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
 HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML)
@@ -352,7 +351,7 @@ clean:
 	$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
 	$(RM) *.pdf
 	$(RM) howto-index.txt howto/*.html doc.dep
-	$(RM) technical/*.html technical/api-index.txt
+	$(RM) technical/*.html
 	$(RM) SubmittingPatches.txt
 	$(RM) $(cmds_txt) $(mergetools_txt) *.made
 	$(RM) manpage-base-url.xsl
@@ -385,12 +384,8 @@ user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-
 	$(TXT_TO_XML) -d book -o $@+ $< && \
 	mv $@+ $@
 
-technical/api-index.txt: technical/api-index-skel.txt \
-	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
-	$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
-
 technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
-$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
+$(patsubst %,%.html,$(API_DOCS) $(TECH_DOCS)): %.html : %.txt \
 	asciidoc.conf GIT-ASCIIDOCFLAGS
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
 
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 9b82564d1a..0fdd93ac95 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -904,9 +904,6 @@ See linkgit:gitworkflows[7] for an overview of recommended workflows.
 See also the link:howto-index.html[howto] documents for some useful
 examples.
 
-The internals are documented in the
-link:technical/api-index.html[Git API documentation].
-
 Users migrating from CVS may also want to
 read linkgit:gitcvs-migration[7].
 
diff --git a/Documentation/technical/.gitignore b/Documentation/technical/.gitignore
deleted file mode 100644
index 8aa891daee..0000000000
--- a/Documentation/technical/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-api-index.txt
diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.txt
deleted file mode 100644
index eda8c195c1..0000000000
--- a/Documentation/technical/api-index-skel.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-Git API Documents
-=================
-
-Git has grown a set of internal API over time.  This collection
-documents them.
-
-////////////////////////////////////////////////////////////////
-// table of contents begin
-////////////////////////////////////////////////////////////////
-
-////////////////////////////////////////////////////////////////
-// table of contents end
-////////////////////////////////////////////////////////////////
diff --git a/Documentation/technical/api-index.sh b/Documentation/technical/api-index.sh
deleted file mode 100755
index 9c3f4131b8..0000000000
--- a/Documentation/technical/api-index.sh
+++ /dev/null
@@ -1,28 +0,0 @@
-#!/bin/sh
-
-(
-	c=////////////////////////////////////////////////////////////////
-	skel=api-index-skel.txt
-	sed -e '/^\/\/ table of contents begin/q' "$skel"
-	echo "$c"
-
-	ls api-*.txt |
-	while read filename
-	do
-		case "$filename" in
-		api-index-skel.txt | api-index.txt) continue ;;
-		esac
-		title=$(sed -e 1q "$filename")
-		html=${filename%.txt}.html
-		echo "* link:$html[$title]"
-	done
-	echo "$c"
-	sed -n -e '/^\/\/ table of contents end/,$p' "$skel"
-) >api-index.txt+
-
-if test -f api-index.txt && cmp api-index.txt api-index.txt+ >/dev/null
-then
-	rm -f api-index.txt+
-else
-	mv api-index.txt+ api-index.txt
-fi
-- 
gitgitgadget

Re: [PATCH 0/1] [Outreachy] doc: remove api-index

[Junio C Hamano]

"Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Remove both api-index.txt and api-index-skel.txt as the API documentation is
> being moved to the header files, so the index is not needed anymore because
> the doc files (Documentation/technical/api-*.txt) will be gone.
>
> Make changes to Documentation/Makefile accordingly.

Why is this not part of the other series?  Without any of them this
step does not make sense, no?

Re: [PATCH 0/1] [Outreachy] doc: remove api-index

[Heba Waly]

On Thu, Nov 7, 2019 at 7:21 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > Remove both api-index.txt and api-index-skel.txt as the API documentation is
> > being moved to the header files, so the index is not needed anymore because
> > the doc files (Documentation/technical/api-*.txt) will be gone.
> >
> > Make changes to Documentation/Makefile accordingly.
>
> Why is this not part of the other series?  Without any of them this
> step does not make sense, no?

Moving it to the other series makes more sense, although I won't
consider it dependent on removing the rest of the files, as we're
changing the location of the documentation anyway, and readers will
need to refer to the code for more info. But I agree with you and will
move it there.

Thanks,
Heba