Skip to content

Commit de5e94b

Browse files
afhafh
authored
Merge pull request #72 from afh/api-documentation
Add Ledger API documentation
2 parents 59e234e + cf1dcc2 commit de5e94b

File tree

7 files changed

+191
-29
lines changed

7 files changed

+191
-29
lines changed

‎.github/workflows/build_and_deploy.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ jobs:
3232
cp result/share/doc/ledger/ledger* build/doc
3333
nix build .#doc-ledger-mode
3434
cp result/ledger-mode.* build/doc
35+
nix build .#doc-ledger-api
36+
cp -R result/share/doc/ledger/html build/doc/api/
3537
- name: Upload artifact
3638
uses: actions/upload-pages-artifact@v1
3739
with:

‎Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ clean:
3535
$(TEXINFO) $(MANPAGE):
3636
$(CURL) --remote-name $(HOST)/$($(@)_repopath)/$@
3737

38-
# TODO: Remove the line after this comment once the next release after 3.3.1
38+
# TODO: Remove the line after this comment once the next release after 3.3.2
3939
# is published as it will include the necessary changes for version.texi and
4040
# related files to be fetched from the tag instead of the master branch.
4141
version.texi: LATEST := master

‎apidoc_header.html

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
<!-- HTML header for doxygen 1.9.6-->
2+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3+
<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
4+
<head>
5+
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
6+
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
7+
<meta name="generator" content="Doxygen $doxygenversion"/>
8+
<meta name="viewport" content="width=device-width, initial-scale=1"/>
9+
<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
10+
<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
11+
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
12+
<!--BEGIN DISABLE_INDEX-->
13+
<!--BEGIN FULL_SIDEBAR-->
14+
<script type="text/javascript">var page_layout=1;</script>
15+
<!--END FULL_SIDEBAR-->
16+
<!--END DISABLE_INDEX-->
17+
<script type="text/javascript" src="$relpath^jquery.js"></script>
18+
<script type="text/javascript" src="$relpath^dynsections.js"></script>
19+
$treeview
20+
$search
21+
$mathjax
22+
$darkmode
23+
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
24+
$extrastylesheet
25+
</head>
26+
<body>
27+
<!--BEGIN DISABLE_INDEX-->
28+
<!--BEGIN FULL_SIDEBAR-->
29+
<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
30+
<!--END FULL_SIDEBAR-->
31+
<!--END DISABLE_INDEX-->
32+
33+
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
34+
35+
<!-- BEGIN LEDGER_HEADER -->
36+
<style type="text/css">
37+
@import url("https://ledger-cli.org/stylesheets/site.css");
38+
header { line-height: 1.3; }
39+
#main-nav { flex-grow: 0; }
40+
header, #main-nav { max-width: 60em; margin: auto; }
41+
header { margin-bottom: 1em; }
42+
@media print { aside, header { display: none; } }
43+
</style>
44+
<aside>
45+
<a href="https://git.ledger-cli.org/ledger" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#151513; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><title>Fork me on GitHub</title><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a>
46+
</aside>
47+
<header>
48+
<nav>
49+
<ul>
50+
<li><a href="/">ledger $projectnumber</a></li>
51+
<li><a href="/index.html">Home</a></li>
52+
<li><a href="/features.html">Features</a></li>
53+
<li><a href="/docs.html">Docs</a></li>
54+
<li><a href="/download.html">Download</a></li>
55+
<li><a href="/contribute.html">Contribute</a></li>
56+
<li><a href="https://wiki.ledger-cli.org/">Wiki</a></li>
57+
</ul>
58+
</nav>
59+
</header>
60+
<!-- END LEDGER_HEADER -->
61+
62+
<!--BEGIN TITLEAREA-->
63+
<div id="titlearea">
64+
<table cellspacing="0" cellpadding="0">
65+
<tbody>
66+
<tr id="projectrow">
67+
<!--BEGIN PROJECT_LOGO-->
68+
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
69+
<!--END PROJECT_LOGO-->
70+
<!--BEGIN PROJECT_BRIEF-->
71+
<td>
72+
<div id="projectbrief">$projectbrief</div>
73+
</td>
74+
<!--END PROJECT_BRIEF-->
75+
<!--END !PROJECT_NAME-->
76+
<!--BEGIN DISABLE_INDEX-->
77+
<!--BEGIN SEARCHENGINE-->
78+
<!--BEGIN !FULL_SIDEBAR-->
79+
<td>$searchbox</td>
80+
<!--END !FULL_SIDEBAR-->
81+
<!--END SEARCHENGINE-->
82+
<!--END DISABLE_INDEX-->
83+
</tr>
84+
<!--BEGIN SEARCHENGINE-->
85+
<!--BEGIN FULL_SIDEBAR-->
86+
<tr><td colspan="2">$searchbox</td></tr>
87+
<!--END FULL_SIDEBAR-->
88+
<!--END SEARCHENGINE-->
89+
</tbody>
90+
</table>
91+
</div>
92+
<!--END TITLEAREA-->
93+
<!-- end header part -->

‎flake.lock

Lines changed: 48 additions & 12 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎flake.nix

Lines changed: 35 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,25 @@
44
nixConfig.bash-prompt = "ledger-cli.org$ ";
55

66
inputs = {
7-
nixpkgs.url = "nixpkgs/nixpkgs-unstable";
7+
nixpkgs.url = "nixpkgs/nixpkgs-unstable"; # provides doxygen 1.9.6
88
flake-utils.url = "github:numtide/flake-utils";
99
# NOTA BENE: When a new release of ledger or ledger-mode is available, update
1010
# the tag in the url below and run `nix flake update`, so that GitHub Actions
1111
# will build the documentation from the latest ledger and ledger-mode release.
12-
# TODO: Replace `master` with the tag of the ledger release following 3.3.1, once available.
12+
# TODO: Replace `master` with the tag of the ledger release following 3.3.2, once available.
1313
ledger.url = "github:ledger/ledger/master";
1414
ledger-mode.url = "github:ledger/ledger-mode/v4.0.0";
1515
ledger-mode.flake = false;
16+
doxygen-awesome.url = "github:jothepro/doxygen-awesome-css/v2.2.0";
17+
doxygen-awesome.flake = false;
1618
};
1719

18-
outputs = { self, nixpkgs, flake-utils, ledger, ledger-mode }:
20+
outputs = { self, nixpkgs, flake-utils, ledger, ledger-mode, doxygen-awesome }:
1921
flake-utils.lib.eachDefaultSystem( system:
2022
let
2123
pkgs = import nixpkgs { inherit system; };
2224
gems = with pkgs; bundlerEnv {
23-
name = "ledger.github.io-gems";
25+
name = "ledger-website-gems";
2426
inherit ruby;
2527
gemdir = ./.;
2628
};
@@ -32,7 +34,7 @@
3234
packages = rec {
3335
default = website;
3436
website = pkgs.stdenvNoCC.mkDerivation rec {
35-
name = "ledger.github.io";
37+
name = "ledger-website";
3638
src = self;
3739

3840
dontConfigure = true;
@@ -52,6 +54,33 @@
5254
'';
5355
};
5456

57+
doc-ledger-api = pkgs.stdenvNoCC.mkDerivation rec {
58+
name = "ledger-api";
59+
60+
src = ledger;
61+
62+
nativeBuildInputs = with pkgs; [
63+
cmake doxygen graphviz # doxygen uses dot from graphviz to create diagrams
64+
];
65+
66+
enableParallelBuilding = false;
67+
68+
preConfigure = "cd doc";
69+
70+
cmakeFlags = [
71+
"-Wno-dev"
72+
"-DUSE_DOXYGEN:BOOL=ON"
73+
"-DDOXYGEN_EXTRA_CSS:STRING=${doxygen-awesome}/doxygen-awesome.css"
74+
"-DDOXYGEN_HTML_HEADER:STRING=${self}/apidoc_header.html"
75+
];
76+
77+
# Ensure the "generated on date at time" footer shows the actual date and time
78+
# when the API documentation was generated.
79+
preBuild = "export SOURCE_DATE_EPOCH=$(date +'%s')";
80+
81+
buildFlags = "doc.doxygen";
82+
};
83+
5584
doc-ledger = pkgs.stdenvNoCC.mkDerivation rec {
5685
name = "ledger";
5786

@@ -65,7 +94,7 @@
6594

6695
preConfigure = "cd doc";
6796

68-
cmakeFlags = [ "-DBUILD_WEB_DOCS:BOOL=ON" "-Wno-dev" ];
97+
cmakeFlags = [ "-Wno-dev" "-DBUILD_WEB_DOCS:BOOL=ON" ];
6998

7099
buildFlags = "doc";
71100

‎source/docs.html.md

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,15 @@ title: Documentation - Ledger
44

55
# Documentation
66

7-
<style>
8-
.dim, .dim a:link, .dim a:visited { color:#ccc; }
9-
</style>
10-
11-
* <b><a href="doc/ledger3.html">Ledger 3 manual</a></b> and <a href="doc/ledger3.pdf">pdf</a> <span class="dim">(<a href="https://git.ledger-cli.org/ledger/commits/master/doc/ledger3.texi">changes</a>)
12-
* <a href="doc/ledger.1.html">Ledger 3 man page</a> and <a href="doc/ledger.1.pdf">pdf</a> <span class="dim">(<a href="https://git.ledger-cli.org/ledger/commits/master/doc/ledger.1">changes</a>)
13-
* <a href="doc/ledger-mode.html">ledger-mode manual</a> and <a href="doc/ledger-mode.pdf">pdf</a> <span class="dim">(<a href="https://git.ledger-cli.org/ledger-mode/commits/master/doc/ledger-mode.texi">changes</a>)
7+
* [**Ledger 3 manual**](doc/ledger3.html) and [pdf](doc/ledger3.pdf) ([changes](https://git.ledger-cli.org/ledger/commits/master/doc/ledger3.texi))
8+
* [Ledger 3 man page](doc/ledger.1.html) and [pdf](doc/ledger.1.pdf) ([changes](https://git.ledger-cli.org/ledger/commits/master/doc/ledger.1))
9+
* [Ledger 3 API documentation](doc/api)
10+
* [ledger-mode manual](doc/ledger-mode.html) and [pdf](doc/ledger-mode.pdf) ([changes](https://git.ledger-cli.org/ledger-mode/commits/master/doc/ledger-mode.texi))
1411

1512
## External links
1613

17-
* The [ledger wiki](https://wiki.ledger-cli.org)
18-
<span class=dim> ([changes](https://wiki.ledger-cli.org/_history)) </span>
14+
* The [ledger wiki](https://wiki.ledger-cli.org) ([changes](https://wiki.ledger-cli.org/_history))
1915
* [ledger on Wikipedia](https://en.wikipedia.org/wiki/Ledger_%28software%29)
20-
<span class=dim> ([changes](https://en.wikipedia.org/w/index.php?title=Ledger_%28software%29&action=history)) </span>
16+
([changes](https://en.wikipedia.org/w/index.php?title=Ledger_%28software%29&action=history))
2117
* John gave a nice audio introduction to Ledger in the [2011/01/26 FLOSS Weekly show](https://twit.tv/floss150)
2218
* hledger.org's [Accounting links](https://hledger.org/accounting.html#accounting-links) has some useful Ledger and accounting links

‎source/stylesheets/site.css.scss

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,12 @@ a[href^="https://"]:not(:has(img, svg))::after {
4343
color:var(--visited-color);
4444
}
4545

46+
// Change color of links pointing to changes
47+
a[href^="https://git.ledger-cli.org"][href*="commits/master"],
48+
a[href*="action=history"],
49+
a[href="https://wiki.ledger-cli.org/_history"]
50+
{ color: #ccc; }
51+
4652
nav {
4753
display:inline;
4854

0 commit comments

Comments
 (0)