Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add documentation generation #477

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add documentation generation #477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
/Documentation/html/
/Documentation/man1/
/Documentation/manpage-base-url.xsl
/t/test-results
/t/trash directory*
/__pycache__/
38 changes: 38 additions & 0 deletions Documentation/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
MAN_BASE_URL := /usr/share/doc/git-doc/
VERSION := $(git log --pretty="%H" -n 1)

ASCIIDOC := asciidoc
ASCIIDOC_EXTRA :=
ASCIIDOC_HTML := xhtml11
ASCIIDOC_DOCBOOK := docbook
ASCIIDOC_CONF := -f asciidoc.conf
ASCIIDOC_COMMON := $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
-amanversion='$(VERSION)' \
-amanmanual='git-filter-repo Manual' -amansource='git-filter-repo'
ASCIIDOC_DEPS := asciidoc.conf
TXT_TO_HTML := $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
TXT_TO_XML := $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
MANPAGE_XSL := manpage-normal.xsl
XMLTO := xmlto
XMLTO_EXTRA := -m manpage-bold-literal.xsl -m manpage-base-url.xsl -m manpage-quote-apos.xsl
XMLTO_DEPS := manpage-bold-literal.xsl manpage-base-url.xsl manpage-quote-apos.xsl

manpage-deps := $(XMLTO_DEPS)
manpage-cmd := $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man

manpage-base-url.xsl: manpage-base-url.xsl.in
sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@

%.xml : %.txt $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<

man1/%.1 : %.xml $(manpage-deps)
mkdir -p man1
$(manpage-cmd) -o man1 $<

html/%.html : %.txt $(ASCIIDOC_DEPS)
mkdir -p html
$(TXT_TO_HTML) -d manpage -o $@ $<

man: man1/git-filter-repo.1
html: html/git-filter-repo.html
78 changes: 78 additions & 0 deletions Documentation/asciidoc.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
## linkgit: macro
#
# Usage: linkgit:command[manpage-section]
#
# Note, {0} is the manpage section, while {target} is the command.
#
# Show Git link as: <command>(<section>); if section is defined, else just show
# the command.

[macros]
(?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=

[attributes]
asterisk=&#42;
plus=&#43;
caret=&#94;
startsb=&#91;
endsb=&#93;
backslash=&#92;
tilde=&#126;
apostrophe=&#39;
backtick=&#96;
litdd=&#45;&#45;

ifdef::backend-docbook[]
[linkgit-inlinemacro]
{0%{target}}
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}
endif::backend-docbook[]

ifdef::backend-docbook[]
ifdef::doctype-manpage[]
# The following two small workarounds insert a simple paragraph after screen
[listingblock]
<example><title>{title}</title>
<literallayout class="monospaced">
|
</literallayout><simpara></simpara>
{title#}</example>

[verseblock]
<formalpara{id? id="{id}"}><title>{title}</title><para>
{title%}<literallayout{id? id="{id}"}>
{title#}<literallayout>
|
</literallayout>
{title#}</para></formalpara>
{title%}<simpara></simpara>
endif::doctype-manpage[]
endif::backend-docbook[]

ifdef::doctype-manpage[]
ifdef::backend-docbook[]
[header]
template::[header-declarations]
<refentry>
<refmeta>
<refentrytitle>{mantitle}</refentrytitle>
<manvolnum>{manvolnum}</manvolnum>
<refmiscinfo class="source">{mansource}</refmiscinfo>
<refmiscinfo class="version">{manversion}</refmiscinfo>
<refmiscinfo class="manual">{manmanual}</refmiscinfo>
</refmeta>
<refnamediv>
<refname>{manname}</refname>
<refpurpose>{manpurpose}</refpurpose>
</refnamediv>
endif::backend-docbook[]
endif::doctype-manpage[]

ifdef::backend-xhtml11[]
[attributes]
git-relative-html-prefix=
[linkgit-inlinemacro]
<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
endif::backend-xhtml11[]
10 changes: 10 additions & 0 deletions Documentation/manpage-base-url.xsl.in
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<!-- manpage-base-url.xsl:
special settings for manpages rendered from newer docbook -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">

<!-- set a base URL for relative links -->
<xsl:param name="man.base.url.for.relative.links"
>@@MAN_BASE_URL@@</xsl:param>

</xsl:stylesheet>
16 changes: 16 additions & 0 deletions Documentation/manpage-bold-literal.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<!-- manpage-bold-literal.xsl:
special formatting for manpages rendered from asciidoc+docbook -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:d="http://docbook.org/ns/docbook"
version="1.0">

<!-- render literal text as bold (instead of plain or monospace);
this makes literal text easier to distinguish in manpages
viewed on a tty -->
<xsl:template match="literal|d:literal">
<xsl:text>\fB</xsl:text>
<xsl:apply-templates/>
<xsl:text>\fR</xsl:text>
</xsl:template>

</xsl:stylesheet>
26 changes: 26 additions & 0 deletions Documentation/manpage-normal.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<!-- manpage-normal.xsl:
special settings for manpages rendered from asciidoc+docbook -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">


<!-- these params silence some output from xmlto -->
<xsl:param name="man.output.quietly" select="1"/>
<xsl:param name="refentry.meta.get.quietly" select="1"/>

<!-- convert asciidoc callouts to man page format -->
<xsl:template match="co">
<xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/>
</xsl:template>
<xsl:template match="calloutlist">
<xsl:text>.sp&#10;</xsl:text>
<xsl:apply-templates/>
<xsl:text>&#10;</xsl:text>
</xsl:template>
<xsl:template match="callout">
<xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/>
<xsl:apply-templates/>
<xsl:text>.br&#10;</xsl:text>
</xsl:template>

</xsl:stylesheet>
16 changes: 16 additions & 0 deletions Documentation/manpage-quote-apos.xsl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">

<!-- work around newer groff/man setups using a prettier apostrophe
that unfortunately does not quote anything when cut&pasting
examples to the shell -->
<xsl:template name="escape.apostrophe">
<xsl:param name="content"/>
<xsl:call-template name="string.subst">
<xsl:with-param name="string" select="$content"/>
<xsl:with-param name="target">'</xsl:with-param>
<xsl:with-param name="replacement">\(aq</xsl:with-param>
</xsl:call-template>
</xsl:template>

</xsl:stylesheet>
17 changes: 3 additions & 14 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,21 +21,10 @@ test:
fixup_locale:
sed -ie s%@@LOCALEDIR@@%$(localedir)% git-filter-repo

# People installing from tarball will already have man1/git-filter-repo.1 and
# html/git-filter-repo.html. But let's support people installing from a git
# clone too; for them, just cheat and snag a copy of the built docs that I
# record in a different branch.
snag_docs: Documentation/man1/git-filter-repo.1 Documentation/html/git-filter-repo.html
doc:
$(MAKE) -C Documentation man html

Documentation/man1/git-filter-repo.1:
mkdir -p Documentation/man1
git show origin/docs:man1/git-filter-repo.1 >Documentation/man1/git-filter-repo.1

Documentation/html/git-filter-repo.html:
mkdir -p Documentation/html
git show origin/docs:html/git-filter-repo.html >Documentation/html/git-filter-repo.html

install: snag_docs #fixup_locale
install: doc #fixup_locale
$(INSTALL) -Dm0755 git-filter-repo "$(DESTDIR)/$(bindir)/git-filter-repo"
$(INSTALL) -dm0755 "$(DESTDIR)/$(pythondir)"
ln -sf "$(bindir)/git-filter-repo" "$(DESTDIR)/$(pythondir)/git_filter_repo.py"
Expand Down