14 KiB
Files
Some views and explanations of files in the hledger project, as of 2022-12.
hledger working copy
A full working copy of the official hledger repos is best laid out like this (manually; we currently don't use git submodules):
src/hledger/ - git clone https://github.com/simonmichael/hledger; cd hledger site/ - git clone https://github.com/simonmichael/hledger_site site finance/ - git clone https://github.com/simonmichael/hledger_finance finance
You don't need to clone all of these repos unless you are working in all of those areas.
The next two listings show the directories in the main and site repos:
main repo directories
The main repo contains the hledger-lib, hledger, hledger-ui, and hledger-web haskell packages, the hledger-install script, a collection of example data, some documentation and other support files.
src/hledger/ .github/ ISSUE_TEMPLATE/ workflows/ old/ .sandstorm/ bin/ checks/ doc/ haskellerz/ hcar/ mockups/ profs/ docker-static-arm32v7/ docker/ examples/ budgeting/ csv/ investing/ invoicing/ invoice-script/ makefile/ reports/ systemd/ templates/ basic/ hledger-install/ hledger-lib/ Hledger/ Data/ JournalChecks/ Read/ Reports/ Utils/ Text/ Megaparsec/ Tabular/ other/ ledger-parse/ Ledger/ Parser/ test/ hledger-ui/ Hledger/ UI/ test/ hledger-web/ Hledger/ Web/ Handler/ Settings/ Widget/ app/ config/ deploy/ static/ css/ fonts/ js/ templates/ test/ hledger/ Hledger/ Cli/ Commands/ app/ bench/ embeddedfiles/ shell-completion/ test/ addons/ balance/ cli/ errors/ i18n/ import/ journal/ account-display-order/ 1/ print/ register/ tools/
site repo directories
The site repo contains the website infrastructure, versioned snapshots of the user manuals, home page, cookbook and other docs.
src/hledger/site/ css/ js/ src/ 1.0/ 1.1/ 1.10/ 1.11/ 1.12/ 1.13/ 1.14/ 1.15/ 1.16/ 1.17/ 1.18/ 1.19/ 1.2/ 1.20/ 1.21/ 1.22/ 1.23/ 1.24/ 1.25/ 1.26/ 1.27/ 1.28/ 1.3/ 1.4/ 1.5/ 1.9/ dev/ fonts/ highslide/ graphics/ outlines/ images/ hledger-ui/ hledger-web/ normal/ small/ theme/ css/
finance repo
The finance repo contains transaction journals and financial reports.
src/hledger/finance/ Makefile README.md oc.accounts oc.csv oc.csv.rules oc.journal
hledger user scripts
Scripts for users are in bin/:
src/hledger/bin/ README.md _hledger-chart.hs bashrc compile.sh csv.mk hledger-addon-example.hs hledger-balance-as-budget.hs hledger-check-fancyassertions.hs hledger-check-postable.hs hledger-check-tagfiles.cabal.hs hledger-check-tagfiles.hs hledger-combine-balances.hs hledger-git hledger-move.hs hledger-pijul hledger-print-location.hs hledger-simplebal hledger-smooth.hs hledger-swap-dates.hs paypaljson paypaljson2csv scripts.test watchaccounts
hledger developer tools
Scripts used by developers and maintainers tend to be in tools/:
src/hledger/tools/ README changelog.hs commitlint criterionbench.hs dayssincetag.hs docshelltest.hs generatejournal.hs generatetimeclock.hs gtree hackageupload listbydeps.hs pandoc-dedent-code-blocks.lua pandoc-demote-headers.lua pandoc-drop-html-blocks.lua pandoc-drop-html-inlines.lua pandoc-drop-links.lua pandoc-drop-toc.lua pandoc-toc.lua pandoc-wiki-links.lua progressionbench.hs regressiontest.py release runhledgercov simplifyprof.hs trhsx
Sh/makefiles
Many developer tasks are automated with Make and/or Shake also.
Run make
or ./Shake
(after make Shake
) to see help.
src/hledger/ Makefile Makefile.helpsys Shake.hs doc/ MAKE.md SHAKE.md haskellerz/ Makefile examples/ invoicing/ makefile/ Makefile reports/ Makefile hledger/ shell-completion/ BSDmakefile Makefile test/ errors/ Makefile
YAML files
Developer configuration often happens in .yaml or .yml files.
src/hledger/ .hlint.yaml azure-pipelines.yml hie-other.yaml stack.yaml stack8.10.yaml stack9.0.yaml stack9.4.yaml .github/ FUNDING.yml ISSUE_TEMPLATE/ config.yml workflows/ binaries-linux-arm32v7-static.yml binaries-linux-x64-static.yml binaries-mac-x64.yml binaries-windows-x64.yml test-linux-x64.yml old/ release.yml hledger-lib/ package.yaml hledger-ui/ package.yaml hledger-web/ package.yaml config/ keter.yaml settings.yml hledger/ package.yaml
Core docs
Core documentation which should stay closely synced with hledger's implementation (changelogs, user manuals, developer docs) is kept in the main repo.
-
Many directories have a README.md explaining their purpose and content.
-
Each hledger package, and the project itself, has a CHANGES.md changelog file.
-
hledger/hledger.m4.md, hledger-ui/hledger-ui.m4.md, hledger-web/hledger-web.m4.md are the user manuals, which get rendered as html, info, man and plain text. They are processed first with m4 for extra flexibility.
-
The hledger manual imports the subcommand docs from hledger/Hledger/Cli/Commands/*.md.
-
doc/ contains other developer docs.
src/hledger/ CHANGES.md README.md .github/ pull_request_template.md ISSUE_TEMPLATE/ a-bug.md a-wish.md .sandstorm/ README.md changelog.md description.md bin/ README.md doc/ ACHIEVEMENTS.md BENCHMARKS.md CHANGELOGS.md CODE.md COMMITS.md CONTRIBUTING.md CREDITS.md DOCS.md EXAMPLES.md FILES.md FINANCE.md ISSUES.md LINKS.md MAKE.md PULLREQUESTS.md RELEASING.md REPOS.md SHAKE.md TESTS.md VERSIONNUMBERS.md DEVWORKFLOWS.md github-release-doc.tmpl.md haskellerz/ haskellerz.md hcar/ HCAR-hledger-201611.md docker/ README.md examples/ invoicing/ README.md invoice-script/ README.md abinvoice.tmpl.md makefile/ 202001ab.md README.md systemd/ hledger-web.service hledger.nginx readme.md templates/ README.md hledger-install/ README.md hledger-lib/ CHANGES.md README.md hledger-ui/ CHANGES.md README.md hledger-ui.m4.md test/ uitest.md hledger-web/ CHANGES.md README.md hledger-web.m4.md hledger/ CHANGES.md README.md hledger.m4.md Hledger/ Cli/ Commands/ Accounts.md Activity.md Add.md Aregister.md Balance.md Balancesheet.md Balancesheetequity.md Cashflow.md Check.md Close.md Codes.md Commodities.md Descriptions.md Diff.md Files.md Help.md Import.md Incomestatement.md Notes.md Payees.md Prices.md Print.md README.md Register.md Rewrite.md Roi.md Stats.md Tags.md Test.md shell-completion/ README.md test/ README.md errors/ README.md
Additional docs
Additional docs (intro pages, faqs, tutorials, cookbook..) are kept in the site repo's src/ directory. index.md is the home page. SUMMARY.md defines the site structure.
Developer docs (UPPERCASE) and the latest dev manuals (dev/*.md) from the main repo are also symbolically linked there, so that they too appear on the website.
src/hledger/site/src/ ACHIEVEMENTS.md BACKLOG.md BENCHMARKS.md CHANGELOGS.md CODE.md COMMITS.md CONTRIBUTING.md CREDITS.md DOCS.md ERRORS.md EXAMPLES.md FILES.md FINANCE.md ISSUES.md LINKS.md MAKE.md PULLREQUESTS.md RELEASING.md REPOS.md ROADMAP.md SHAKE.md SUMMARY.md TESTS.md VERSIONNUMBERS.md DEVWORKFLOWS.md accounting.md balancing-the-accounting-equation.md basics.md beancount.md budgeting-and-forecasting.md budgeting.md change-account-name-separator.md charts.md checking-for-errors.md command-line-completion.md common-journal-entries.md common-workflows.md conversion2.md cookbook.md create-a-journal.md currency-conversion.md dev-README.md dev.md dsq.md editors.md export.md faq.md features.md financerepo.md finfaq.md forecasting.md foreign-trip-expenses.md gain.md gnucash.md hledger-web-tips.md import-csv.md index.md install.md inventory.md investments.md invoicing.md ledger.md loans.md manuals.md mobile.md mockups.md multicurrency-tutorial.md project-accounting.md quicken.md 2-minute-quick-start.md 5-minute-quick-start.md release-notes.md report-examples.md rewrite-account-names.md rewrite-commodity-symbols.md roi.md save-frequently-used-options.md scripting.md scripts.md simons-setup.md snippets.md sponsor.md sqlite.md start.md support.md tags-tutorial.md time-planning.md time-to-money.md track-changes-with-version-control.md track-investments.md ui.md videos.md web.md 1.0/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.1/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.10/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.11/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.12/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.13/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.14/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.15/ csv.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.16/ csv.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.17/ csv.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.18/ csv.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.19/ csv.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.2/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.20/ csv.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.21/ hledger-ui.md hledger-web.md hledger.md 1.22/ hledger-ui.md hledger-web.md hledger.md 1.23/ hledger-ui.md hledger-web.md hledger.md 1.24/ hledger-ui.md hledger-web.md hledger.md 1.25/ hledger-ui.md hledger-web.md hledger.md 1.26/ hledger-ui.md hledger-web.md hledger.md 1.27/ hledger-ui.md hledger-web.md hledger.md 1.28/ hledger-ui.md hledger-web.md hledger.md 1.3/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.4/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.5/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md 1.9/ csv.md hledger-api.md hledger-ui.md hledger-web.md hledger.md journal.md timeclock.md timedot.md dev/ hledger-ui.md hledger-web.md hledger.md
Site config files
These help configure the website.
-
book.toml is the main config file for mdbook.
-
src/SUMMARY.md defines the site's pages and which ones appear in the sidebar (except for old manual versions; those are rendered separately).
src/hledger/site/ Makefile book.toml css/ site.css js/ bootstrap.min.js jquery-1.11.0.min.js site.js src/ SUMMARY.md highslide/ highslide-ie6.css highslide.css highslide.js theme/ book.js favicon.png favicon.svg highlight.css highlight.js index.hbs css/ chrome.css general.css print.css variables.css