mirror of
https://github.com/simonmichael/hledger.git
synced 2024-09-19 10:17:35 +03:00
doc: expand doc/README, describe doc files and workflows
This commit is contained in:
parent
1d2580886f
commit
d637e2fbcd
90
doc/README
90
doc/README
@ -1,20 +1,88 @@
|
|||||||
Miscellaneous project docs that don't fit elsewhere.
|
HLEDGER_SRC/doc - starting point for hledger documentation files.
|
||||||
See also:
|
|
||||||
|
|
||||||
- the project readme in the top directory
|
|
||||||
- the package changelogs and man pages in hledger-lib/, hledger/ etc.
|
|
||||||
- the website content in site/
|
|
||||||
|
|
||||||
Some doc notes, until a better place is found:
|
hledger doc files can be divided into several groups:
|
||||||
|
|
||||||
In site/release-notes.md, we stopped mentioning minor releases
|
1. Project admin/dev notes not published on the website.
|
||||||
around 0.27. The old minor releases should probably be removed
|
These are kept in this directory (doc/). They include:
|
||||||
or promoted to the same heading level as major releases.
|
|
||||||
|
doc/finance/ project finances
|
||||||
|
doc/hcar/ Haskell Community and Activities Report entries
|
||||||
|
doc/lib.m4 common macros used in package manuals
|
||||||
|
doc/manpage.* misc. templates for rendering package manuals
|
||||||
|
doc/mockups/ exploratory developer mockups
|
||||||
|
doc/profs/ a place for long-term profiling/performance data
|
||||||
|
|
||||||
|
2. Project doc files required to be in the top directory:
|
||||||
|
|
||||||
|
README.md the main project readme, displayed on github
|
||||||
|
LICENSE the default project license
|
||||||
|
|
||||||
|
3. Per-package descriptions, readmes, changelogs, and reference manuals.
|
||||||
|
These are in the respective package directories:
|
||||||
|
|
||||||
|
hledger*/package.yaml source for package metadata (description, etc.)
|
||||||
|
hledger*/README package readme, displayed on hackage
|
||||||
|
hledger*/CHANGES package changelog, displayed on hackage
|
||||||
|
hledger*/doc/hledger*.m4.md package manual source file(s)
|
||||||
|
|
||||||
|
4. The project website and additional docs - home page, FAQ, tutorials,
|
||||||
|
how-tos, developer guide, etc. These are in the site directory:
|
||||||
|
|
||||||
|
site/ hledger.org website content, templates, assets
|
||||||
|
|
||||||
|
|
||||||
|
Workflows:
|
||||||
|
|
||||||
|
The manuals and website are rendered from the top directory,
|
||||||
|
primarily using Shake. First, build Shake:
|
||||||
|
|
||||||
|
$ make Shake
|
||||||
|
|
||||||
|
Then render the per-package manuals from markdown-m4 source files (*.m4.md)
|
||||||
|
to text, man, info, and markdown formats. This requires some unix tools
|
||||||
|
such as m4:
|
||||||
|
|
||||||
|
$ ./Shake manuals
|
||||||
|
|
||||||
|
Then render the website. This copies the manuals' markdown files into
|
||||||
|
the website, edits them for web display, concatenates them to form the
|
||||||
|
one-page manual, and runs hakyll-std (a generic hakyll script, included)
|
||||||
|
to render everything as html and add site header/footer,
|
||||||
|
tables of contents, etc.:
|
||||||
|
|
||||||
|
$ ./Shake website
|
||||||
|
|
||||||
|
View the rendered website ("open" is mac-specific; use your equivalent):
|
||||||
|
|
||||||
|
$ open site/_site/index.html
|
||||||
|
|
||||||
|
Or run hakyll in preview mode, regenerating html when source changes:
|
||||||
|
|
||||||
|
$ make site-preview
|
||||||
|
$ open http://localhost:8000
|
||||||
|
|
||||||
|
Example workflow: edit doc source files, run Shake website in another window,
|
||||||
|
wait for to hakyll rebuild html files, manually reload pages in browser.
|
||||||
|
Occasionally hakyll will get confused, to fix it: ctrl-c, make site-clean site-preview .
|
||||||
|
|
||||||
|
You can automate the browser page reloading by running a livereloadx proxy.
|
||||||
|
In another window:
|
||||||
|
|
||||||
|
$ make site-reload
|
||||||
|
$ open http://localhost:8001 # if the make file didn't do it
|
||||||
|
|
||||||
|
|
||||||
|
Misc. notes:
|
||||||
|
|
||||||
|
Changelogs are plain text, but started including some markdown formatting
|
||||||
|
from 1.0. Should make consistent.
|
||||||
|
|
||||||
Changelogs started mentioning committer names from 2017/1,
|
Changelogs started mentioning committer names from 2017/1,
|
||||||
for hledger-ui-1.1.1 (because they won't appear on the release notes).
|
for hledger-ui-1.1.1 (because they won't appear on the release notes).
|
||||||
Could do it just for minor releases but might as well do it for all.
|
Could do it just for minor releases but might as well do it for all.
|
||||||
Could do it for past releases but no pressing need.
|
Could do it for past releases but no pressing need.
|
||||||
|
|
||||||
Changelogs are plain text, but started including some markdown formatting
|
In site/release-notes.md, we stopped mentioning minor releases
|
||||||
from 1.0, for ease of pasting from release notes ? Should make consistent.
|
around 0.27. The old minor releases should probably be removed
|
||||||
|
or promoted to the same heading level as major releases.
|
||||||
|
@ -1,2 +1,4 @@
|
|||||||
Documentation from the other hledger packages, included here for
|
A local copy of all the other hledger packages' rendered manuals,
|
||||||
embedding into the hledger program.
|
for embedding into the hledger program via Hledger/Cli/DocFiles.hs.
|
||||||
|
(Because you can only embed relative file paths which are under
|
||||||
|
the current package directory, IIRC).
|
||||||
|
Loading…
Reference in New Issue
Block a user