beancount / docs

Beancount Documentation.

Beancount Documentation

https://beancount.github.io/docs/

Source files are in docs directory.

These documents in markdown format are automatically generated from official Beancount documentation.

You can contribute.

Beancount Google Doc converter

Installation

The converter requires python 3.6 - 3.10.

Create virtualenv (recommended):

python3 -m venv venv
. venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Usage

Export and convert single document:

# Export google document as docx file
python export.py document "100tGcA4blh6KSXPRGCZpUlyxaRUwFHEvnz_k9DyZFn4" doubleentry.docx
# Export drawings
python export.py drawings "100tGcA4blh6KSXPRGCZpUlyxaRUwFHEvnz_k9DyZFn4" drawings
# Convert docx file to markdown
python export.py convert doubleentry.docx doubleentry.md --drawing-dir=drawings

Export and convert all documents:

python crawl.py

Documentation website

Generate static website using MkDocs:

python build.py serve

Deploy to GitHub pages:

python build.py gh-deploy

docs's Issues

Strip quotes around code

In the Google docs quotes are often used around text which uses Consolas font. On the Google docs this looks fine. But on the converted docs, this looks odd because of the way code is highlighted. I therefore suggest to strip quotes around text that is completely Consolas.

An example is here: https://xuhcc.github.io/beancount-docs/01_command_line_accounting_in_context.html

The CAFE MOGADOR NEW YO bit is the

I think it makes sense to make this change as part of the Markdown conversion simply because these code elements are displayed differently to Google Docs and so it doesn't make sense to change the original document.

(This is different to issue #7)

How to trigger documntation regeneration

Is there a way to trigger the regeneration of the documentation or is it a manual process?

Convert quoted arguments into code?

The manual has stuff like:

characters with the “-w” option.
“--render-balance”

I wonder if everything that looks like an an argument (i.e. something like ^-[\w-]) should be converted to `code`.

Other things that might be converted like this:

• single characters: e.g.

Tags must begin with “#”, and links with “^”.

• maybe dates: \d\d[./]\d\d[./]\d\d

Add Search functionality

These docs are wonderful, an by far my preferred method of finding beancount info. However, I would love to see a Search functionality (similar to what is on aumayr's doc page). The categorization in beancount's documentation is not always obvious and being able to find the proper section without going back to google would be nice (especially since Google has apparently not yet indexed the new doc location)

Convert UTF-8 quotes in code elements

We sometimes see UTF-8 quotes in code elements like

YYYY-MM-DD open Account [ConstraintCurrency,...] [“BookingMethod”]

Since this is invalid, I am wondering if the conversion should fix that.

(I'll try to fix the Google docs as well.)

Doesn't work with python 3.10

beancount-docs uses pandoc to convert between exported docx documents and markdown. Versions of pandoc greater than 2.7.2 have a bug which prevents them from converting documents correctly (see jgm/pandoc#5971) so we can not use them. Package py-pandoc was used to easily install pandoc 2.7.2 with pip but it fails to install on python 3.10 (it failed on 3.9 too but maintainer agreed to publish a new version kiwi0fruit/py-pandoc#4).

RuntimeError: Pandoc died with exitcode "83" during conversion: b' File "filter.py", line 39\n def resolve_url(url: str) -> str:\n

Hi, I was trying to build locally, but after pip3 install -r requirements.txt, I get the following.

$ python3 crawl.py 
Found 32 documents
Processing https://docs.google.com/document/d/1RaondTJCS_IUPBHFNdT8oqFKJjVJDsfsn6JEjBG04eA/
Traceback (most recent call last):
  File "crawl.py", line 65, in <module>
    main()
  File "crawl.py", line 59, in main
    convert(document, output_path)
  File "/Users/alice/code/beancount-docs/export.py", line 125, in convert
    outputfile=output,
  File "/usr/local/lib/python3.7/site-packages/pypandoc/__init__.py", line 103, in convert_text
    outputfile=outputfile, filters=filters)
  File "/usr/local/lib/python3.7/site-packages/pypandoc/__init__.py", line 325, in _convert_input
    'Pandoc died with exitcode "%s" during conversion: %s' % (p.returncode, stderr)
RuntimeError: Pandoc died with exitcode "83" during conversion: b'  File "filter.py", line 39\n    def resolve_url(url: str) -> str:\n                       ^\nSyntaxError: invalid syntax\nError running filter filter.py:\nFilter returned error status 1\n'

07_beancount_options_reference.html is hard to read

The formatting is off. It appears to be a combination of the indentation being lost and the paragraphs not being formatted like the source.

https://docs.google.com/document/d/1_-T_BvDtUjj9M7liZMNSkrL8pgC60TGMBlYCiV1e4ZM/edit

And the output:

If configurable in pandoc, an option would be to use a definition-list, DL.
In the current theme, the following HTML:

<dl>
  <dt>option “account_previous_balances” “Opening-Balances"</dt>
  <dd>Leaf name of the equity account used for summarizing previous 
transactions into opening balances.</dd>
</dl>

Shows up as:

No documentation for beancount.tools

For some reason mkdocstrings fails to generate documentation for beancount.tools:

Traceback (most recent call last):
  File "/venv/lib/python3.8/site-packages/pytkdocs/cli.py", line 179, in main
    print(json.dumps(process_json(line)))
  File "/venv/lib/python3.8/site-packages/pytkdocs/cli.py", line 116, in process_json
    return process_config(json.loads(json_input))
  File "/venv/lib/python3.8/site-packages/pytkdocs/cli.py", line 93, in process_config
    obj = loader.get_object_documentation(path, members)
  File "/venv/lib/python3.8/site-packages/pytkdocs/loader.py", line 210, in get_object_documentation
    root_object = self.get_module_documentation(leaf, members)
  File "/venv/lib/python3.8/site-packages/pytkdocs/loader.py", line 297, in get_module_documentation
    leaf = get_object_tree(f"{path}.{modname}")
  File "/venv/lib/python3.8/site-packages/pytkdocs/loader.py", line 146, in get_object_tree
    obj = getattr(current_node.obj, obj_name)
AttributeError: module 'beancount.tools' has no attribute 'sheets_upload'

Inline code change broke code paragraphs

It seems multi-line code paragraphs were broken by commit 0091d1b.

For example:

-    import beancount.loader  
-    …  
-    entries, errors, options = beancount.loader.load\_file(‘myfile.ledger’)  
-    for entry in entries:  
-    …
+    `import beancount.loader … entries, errors, options = beancount.loader.load_file(‘myfile.ledger’) for entry in entries: …`

-    **easy\_install-3.4 pip  
-    **Make sure you invoke the version of easy\_install which matches your Python version, e.g. easy\_install-3.5 if you have Python 3.5 installed, or more.
+    **`easy_install-3.4 pip `**Make sure you invoke the version of easy\_install which matches your Python version, e.g. easy\_install-3.5 if you have Python
 3.5 installed, or more.

-    2015-11-20 price ITOT    95.46 USD
-    2015-11-20 price LQD    115.63 USD
-    2015-11-21 price USD   1.33495 CAD
-    …
+`2015-11-20 price ITOT 95.46 USD 2015-11-20 price LQD 115.63 USD 2015-11-21 price USD 1.33495 CAD …`

How do you trigger the pages-build-deployment action?

Hi @xuhcc ,
Thanks for your continued update of the ReST docs.
I just crawled and pushed, but I wonder how your trigger the pages-build-deployment action.

Beancount org migration to-do

• Update repo url in documentation: https://docs.google.com/document/d/1Z37bQ45wDtjTPaMQ_x-f33p1trH9fNosEAUgbQXwp30/edit#heading=h.wcyqutvazcon
• Update url in repo description.
• Update awesome-beancount.
• Update https://plaintextaccounting.org/#general-accounting

Always convert font consolas to code

Maybe I'm wrong but it seems that font "consolas" should always be converted to Markdown code.

For example at https://docs.google.com/document/d/1s0GOZMcrKKCLlP29MD7kHO4L88evrwWdIO0p4EwRBE0/ we have:

Null objects (NULL)

NULL is in consolas font. And in fact: Null objects (NULL) looks better to me.

Is there a reason this is not done? Maybe there's a good reason.

Links refer to .md instead of .html

The link in the footnote at the end of the intro refers to the .md extension instead of .html

Consider mkdocs or sphinx instead of jekyll

I forked your project here, it is awesome, just having access to the docs as markdown is a big win for me. I noted the jekyll site, and wondered if mkdocs could improve the experience. I realize there is an attempt to use Sphinx, I'm not sure if they can improve beyond current implementation. If I understand correctly, one limitation of readthedocs theme is, it's limited to depth two. Not sure if that is relevant here. I have a prototype of a MkDocs version of your site, at https://bradyt.github.io/beancount-docs/. I suspect it would be trivial to add an "edit page" button. I'm not sure yet how to fix rendering of in-page table of contents into left pane (or top of page for narrow screens). I'm not sure yet how to fix the linking of images.

(I had some errors running crawl.py, but hoping to ignore that until I really have to spend time on it.)

Generate PDF

It would be nice to generate a PDF.

It seems there are several options to generate PDFs, including:

https://github.com/zhaoterryy/mkdocs-pdf-export-plugin

https://github.com/comwes/mkpdfs-mkdocs-plugin

List split into two

This list under "Tags" at https://xuhcc.github.io/beancount-docs/24_beancount_design_doc.html (search for "Tags are sets of strings that can be used to group sets of") is split into two lists:

<li>All transactions during a particular travel might be tagged to later summarize your trip expenses. Those transactions will usually occur around the same date and therefore there is convenient syntax used to automatically tag many transactions that are declared together in a file.</li>
</ul>
<!-- -->
<ul>
<li>

Looking at the Google doc is looks like a single list. Is this a problem with the conversion or the Google doc?

Some pages missing in conversion

https://xuhcc.github.io/beancount-docs/06_beancount_language_syntax.html says

For a deeper discussion of how and when to use payees or not, see Payees, Subaccounts, and Assets.

Also:

Same for "There is a proposal pending to allowing"

Both are links to Same for furius.ca. Any reason these aren't converted?

Add clarification about how to contribute to README

I wanted to make a (small) edit to https://beancount.github.io/docs/external_contributions.html (to add the full list of the existing importers of @tarioch https://github.com/tarioch/beancounttools), and figured this Git repo is the source of that site.

It's just not clear (to me) yet, neither from the README nor the CONTRIBUTING, how one may raise a PR or suggest an edit - in whatever form the maintainers of this (amazing) community prefer.

CONTRIBUTING says to check this thread which I have glanced over but still not understood how to.

Perhaps this could be clarified; I'm happy to raise a PR if when I learn how you like contribs.

@bradyt @xuhcc

Thoughts on Modernizing the Docs Website

Hi! I'm a longtime Beancount user, and I'm super grateful to the hard work of all the maintainers. I've been reading about v3 for a few months now, and I heard that some changes are on their way in regards to the docs (e.g. moving away from Google docs and removing the dependency on furius.ca.

Given this transition, I was wondering if there was also interest in transitioning away from MkDocs to a more custom solution with a custom theme instead of Read the Docs. I'm open to ideas—and I'm flexible in implementation details—but I was thinking something along the lines of Astro with Starlight or Next.js with Nextra. Both options would allow to reuse the existing markdown documentations, I also believe they both offer enough flexibility to accommodate any other requirements the team might have.

I realize that there's not an explicit need for this, so I totally understand if this is not something you're interested in pursuing. However, if it is, I'd be more than happy to take responsibility for doing this.

Please feel free to let me know your thoughts! Thank you for your time.

Paragraph gets pulled into code block

The first paragraph of text after the first code block in this section https://beancount.github.io/docs/getting_started_with_beancount.html#emacs get incorrectly included in the code block. I don't see anything obviusly wrong with the Google Docs document. How can I fix this?