Documentation is now read-only

749 views
Skip to first unread message

Martin Blais

unread,
Aug 6, 2017, 1:52:54 PM8/6/17
to Beancount
Hi,
Much of the intentional comments on Beancount docs have been very useful and an effective way to communicate with users and answer various questions; they have helped improve the quality of the documentation tremendously. However, 90% of the comment emails I get are the result of "finger fart", that is, accidental edits which I have to manually undo one-by-one in order to keep the docs looking sane. I have to find some other solution, as I'm tired of attending to those every day.

So for now I've made the docs read-only.
If you need to comment, I think there might be a way to request comment access.
Otherwise, try the mailing-list...

Stefano Zacchiroli

unread,
Aug 6, 2017, 3:41:12 PM8/6/17
to bean...@googlegroups.com
On Sun, Aug 06, 2017 at 01:52:31PM -0400, Martin Blais wrote:
> So for now I've made the docs read-only.
> If you need to comment, I think there might be a way to request comment
> access.
> Otherwise, try the mailing-list...

So, this makes me wonder: given the main argument for having
documentation on Google Docs was the ease of submitting and receiving
user contributions, would you be open to reconsider that decision now?

Thanks for considering,
Cheers.
--
Stefano Zacchiroli . za...@upsilon.cc . upsilon.cc/zack . . o . . . o . o
Computer Science Professor . CTO Software Heritage . . . . . o . . . o o
Former Debian Project Leader & OSI Board Director . . . o o o . . . o .
« the first rule of tautology club is the first rule of tautology club »

Martin Blais

unread,
Aug 6, 2017, 11:54:32 PM8/6/17
to Beancount
On Sun, Aug 6, 2017 at 3:40 PM, Stefano Zacchiroli <za...@upsilon.cc> wrote:
On Sun, Aug 06, 2017 at 01:52:31PM -0400, Martin Blais wrote:
> So for now I've made the docs read-only.
> If you need to comment, I think there might be a way to request comment
> access.
> Otherwise, try the mailing-list...

So, this makes me wonder: given the main argument for having
documentation on Google Docs was the ease of submitting and receiving
user contributions, would you be open to reconsider that decision now?

I've been trying to automatically convert the gdocs to a Markdown file, but so far my efforts have failed to produce something that looks good enough. I'd like to automate this conversion and publish a copy of Dominik Aumayr's static docs with the gdocs embedded in them. To be fair I haven't had much time to fiddle open source lately (new role at work and all my free time is now going toward that and related reading).

Dominik Aumayr

unread,
Aug 7, 2017, 1:04:00 AM8/7/17
to bean...@googlegroups.com
> I'd like to automate this conversion and publish a copy of Dominik Aumayr's static docs with the gdocs embedded in them.

If you need help with that, or if I should update/modify the static docs to better suit your needs and the transition, just let me know. Happy to help!

- Dominik
> --
> You received this message because you are subscribed to the Google Groups "Beancount" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
> To post to this group, send email to bean...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/CAK21%2BhMJxvRS2g%3D5T55s0%2B9H8iz%2B5O%2BtEsZADDd3wG1Y1spTxw%40mail.gmail.com.
> For more options, visit https://groups.google.com/d/optout.

Martin Blais

unread,
Aug 8, 2017, 10:12:52 PM8/8/17
to Beancount
 Hi Dominik, 
Thanks for your offer.
I could indeed surely use some help with document conversion.

Let me tell you what I did so far, and you can decide then. 
My goal is automatically download and convert the documentation from Google Docs, in a repeatable way.
(I don't really want to move away from it as the pristine source--I have an idea for another way to avoid its shortfalls. 
Even any case, even in the unlikely case this ended up being a final conversion, it would be best automated.)

So what I've done is wrote a script against the API to download the various available conversions of it, and then tried various conversions to Markdown using different tools. Some sparse notes here:

A basic download-and-convert script here:

In short, the result of this experiment is that it looks like "docx" is the downloadable format which yields the most structured information.
However, it is missing some crucial elements, so the final conversion method will have to combine informations extracted from multiple formats and/or conversions.
Moreover, I have found it difficult to produce the "code blocks" in a way that preserves indentation.

So I was thinking of writing a script that would do three things for each document:
- Combine the various elements from the different exported formats
- Fixup some of the invalid converted syntax
- Automatically recover the code blocks using heuristics to reindent them
in order to produce something that would render really nice to Markdown.

I should download all the formats and make them available somewhere as I'm not sure if you can run this script on the API.
It should be possible - and faster anyway - to write code against all the files exported to the file system.

To be fair, I haven't spent a whole lot of time on this yet. Also, I'm a bit of a perfectionist; you could feel free to drive this more scrappy and pragmatically if you like, it might be a better way to get this done.

Let me know if you'd like a download of all the static exports.





On Mon, Aug 7, 2017 at 1:03 AM, Dominik Aumayr <dom...@aumayr.name> wrote:
> I'd like to automate this conversion and publish a copy of Dominik Aumayr's static docs with the gdocs embedded in them.

If you need help with that, or if I should update/modify the static docs to better suit your needs and the transition, just let me know. Happy to help!

- Dominik


> Am 07.08.2017 um 05:54 schrieb Martin Blais <bl...@furius.ca>:
>
> On Sun, Aug 6, 2017 at 3:40 PM, Stefano Zacchiroli <za...@upsilon.cc> wrote:
> On Sun, Aug 06, 2017 at 01:52:31PM -0400, Martin Blais wrote:
> > So for now I've made the docs read-only.
> > If you need to comment, I think there might be a way to request comment
> > access.
> > Otherwise, try the mailing-list...
>
> So, this makes me wonder: given the main argument for having
> documentation on Google Docs was the ease of submitting and receiving
> user contributions, would you be open to reconsider that decision now?
>
> I've been trying to automatically convert the gdocs to a Markdown file, but so far my efforts have failed to produce something that looks good enough. I'd like to automate this conversion and publish a copy of Dominik Aumayr's static docs with the gdocs embedded in them. To be fair I haven't had much time to fiddle open source lately (new role at work and all my free time is now going toward that and related reading).
>
>
> --
> You received this message because you are subscribed to the Google Groups "Beancount" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.

> To post to this group, send email to bean...@googlegroups.com.
--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.

To post to this group, send email to bean...@googlegroups.com.

Zhuoyun Wei

unread,
Aug 13, 2017, 12:15:17 PM8/13/17
to bean...@googlegroups.com
Glad to hear Beancount moves on from Google Docs.

No offense. But I was very confused when I first met Beancount. Google
Docs is a very good collaborating platform but a poor choice for
software documentation. I remember when I needed to look up for some
syntax or usage I cannot search thru the documention because
"site:docs.google.com beancount" does not return any useful results [1]
-- it's very ironic that a search engine does not index its sibling
website well. The Docs page itself is slow to load compared to simple
HTML (without a ton of AJAX) or plain text documentation that were
popular among open source projects.

Cheers!


[1] https://www.google.com/search?q=site%3Adocs.google.com+beancount


--
Zhuoyun Wei
signature.asc

Martin Blais

unread,
Aug 13, 2017, 1:16:29 PM8/13/17
to Beancount
On Sun, Aug 13, 2017 at 12:15 PM, Zhuoyun Wei <wzy...@wzyboy.org> wrote:
Glad to hear Beancount moves on from Google Docs.

It's not.
It would just be nice to have a conversion from Docs to something static, for people like you who don't like the Docs format.



--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.
To post to this group, send email to bean...@googlegroups.com.

jke...@gmail.com

unread,
Aug 14, 2017, 1:26:59 AM8/14/17
to Beancount
I'm not hugely excited about Google products in general due to their corrosively broad erosion of privacy in society (same thing goes for Facebook's platform in my opinion). But given that you've found Google Docs efficient for producing quality documentation, great. Having good documentation is really helpful.

However, I agree with Zhoyun Wei that I find the Google Docs solution difficult to search against all the beancount documentation when I'm looking for something.

Is there an easy way to search beancount's documentation within Google Docs?

Thanks!


Le dimanche 13 août 2017 19:16:29 UTC+2, Martin Blais a écrit :
On Sun, Aug 13, 2017 at 12:15 PM, Zhuoyun Wei <wzy...@wzyboy.org> wrote:
Glad to hear Beancount moves on from Google Docs.

It's not.
It would just be nice to have a conversion from Docs to something static, for people like you who don't like the Docs format.



No offense. But I was very confused when I first met Beancount. Google
Docs is a very good collaborating platform but a poor choice for
software documentation. I remember when I needed to look up for some
syntax or usage I cannot search thru the documention because
"site:docs.google.com beancount" does not return any useful results [1]
-- it's very ironic that a search engine does not index its sibling
website well. The Docs page itself is slow to load compared to simple
HTML (without a ton of AJAX) or plain text documentation that were
popular among open source projects.

Cheers!


[1] https://www.google.com/search?q=site%3Adocs.google.com+beancount


--
Zhuoyun Wei

--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.

To post to this group, send email to bean...@googlegroups.com.

Martin Blais

unread,
Aug 14, 2017, 1:54:05 AM8/14/17
to Beancount
On Mon, Aug 14, 2017 at 1:26 AM, <jke...@gmail.com> wrote:
I'm not hugely excited about Google products in general due to their corrosively broad erosion of privacy in society (same thing goes for Facebook's platform in my opinion).

No comment.

 
But given that you've found Google Docs efficient for producing quality documentation, great. Having good documentation is really helpful.

It's unparalleled. Static documentation doesn't even come close. The advantages are two-fold it's the effective collaboration (theoretically possible collaboration is pointless if nobody ever sends a patch) and the immediacy of it (even I wouldn't bother loading up the file in Emacs and finding the trouble spot if I see a typo in the midst of doing something else). The problem with open source solutions is that users are programmers and focus their attention on the artifact (the file format), which is mostly irrelevant for the reader. The problem to solve is "How do I work to best to produce a relevant text?" "How do I know if what I wrote is unclear?"

Innovation sometimes requires doing unusual things. I'm not one to follow the crowd, I think for myself (and the OSS crowd really is just another crowd, and in some areas, a very conservative one at that). Yes, it's weird for an open source project, but we've learned useful things from the experience. Nothing is perfect.


However, I agree with Zhoyun Wei that I find the Google Docs solution difficult to search against all the beancount documentation when I'm looking for something.

Is there an easy way to search beancount's documentation within Google Docs?

AFAIK you can search from the Drive interface. Just add the word "beancount" and some terms.




To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.

To post to this group, send email to bean...@googlegroups.com.

Zhuoyun Wei

unread,
Aug 14, 2017, 2:46:39 AM8/14/17
to bean...@googlegroups.com
2017-08-14 01:53:41 Martin Blais <bl...@furius.ca>:
>
>
> AFAIK you can search from the Drive interface. Just add the word "beancount" and some terms.
>

It suddenly occurred to me that since the Docs is now read-only, could
we utilize the /pub feature [1] of Docs? I am not sure if this helps
Google and other search engines to better index the page, but it does at
lease provide a more light-weight web page, without those menu bars,
edit controls, and avatars on the top-right corner showing who are
viewing the same page with you.

[1] One could just change "/edit" to "/pub" in the URL to get a
"published" version of the Docs, so it's easy to update existing links
in the source code. The owner of the Docs have to enable the feature
first.

--
Zhuoyun Wei
signature.asc

Stefano Zacchiroli

unread,
Aug 14, 2017, 3:43:15 PM8/14/17
to bean...@googlegroups.com
On Mon, Aug 14, 2017 at 01:53:41AM -0400, Martin Blais wrote:
> > Is there an easy way to search beancount's documentation within
> > Google Docs?
>
> AFAIK you can search from the Drive interface. Just add the word
> "beancount" and some terms.

AFAICT this works only if you are logged into a Google account, and have
added all Beancount documents to your "drive".

If there is a way to make this work without (being logged into) a Google
account, I'm interested in learning about it.

Martin Blais

unread,
Aug 14, 2017, 11:29:54 PM8/14/17
to Beancount
On Mon, Aug 14, 2017 at 3:42 PM, Stefano Zacchiroli <za...@upsilon.cc> wrote:
On Mon, Aug 14, 2017 at 01:53:41AM -0400, Martin Blais wrote:
> > Is there an easy way to search beancount's documentation within
> > Google Docs?
>
> AFAIK you can search from the Drive interface. Just add the word
> "beancount" and some terms.

AFAICT this works only if you are logged into a Google account, and have
added all Beancount documents to your "drive".

If there is a way to make this work without (being logged into) a Google
account, I'm interested in learning about it.

I could whine here about the advocacy on the mailing-list---as you already know, I don't care much for it. I'm a pragmatist. I have no qualms about using a superior product even if it is built and maintained by a corporation. (Plus, I think Google is an awesome company with a genuine respect for user privacy.)

But let me not do that and instead turn your bottomless energy into a productive channel: as soon as I find some free time I'll download all the exported formats from Google Docs for each of the docs under well organized naming and place them somewhere you can access and download them. If you can build some way to automatically convert from any combination of those into Markdown format that would process and look really nice under Sphinx processing, I'll be happy to hook that conversion routine into the API calls and make /that/ an official mirror of the documentation. After all, there's nothing quite like scratching your own itch.

Sounds like a deal?

Stefano Zacchiroli

unread,
Aug 15, 2017, 6:05:09 PM8/15/17
to bean...@googlegroups.com
On Mon, Aug 14, 2017 at 11:29:30PM -0400, Martin Blais wrote:
> I could whine here about the advocacy on the mailing-list---as you
> already know, I don't care much for it. I'm a pragmatist.
>
> But let me not do that and instead turn your bottomless energy into a
> productive channel:

This is not the first time that I've the feeling you read much more in
my posts than there is to it---the other time was when I was trying to
figure out which precise version of a license Beancount was distributed
under, which was unclear at the time (and you've fixed since, thank
you!).

You mentioned a feature I'm personally interested in: search throughout
the entire Beancount documentation, rather than document by document.
As per your suggestion I've tried to make it work in my specific
condition, and it didn't work for me. Hence my message here, asking to
people more experienced than me in using Google Docs, if I was missing
something or not. It's as simple as that.

If I were "advocating", I would've been way more clear, I'm not a sneaky
person.

> as soon as I find some free time I'll download all the exported
> formats from Google Docs for each of the docs under well organized
> naming and place them somewhere you can access and download them. If
> you can build some way to automatically convert from any combination
> of those into Markdown format that would process and look really nice
> under Sphinx processing, I'll be happy to hook that conversion routine
> into the API calls and make /that/ an official mirror of the
> documentation. After all, there's nothing quite like scratching your
> own itch.
>
> Sounds like a deal?

That would be awesome, yes.

I'm also glad you're treating requests posted here (an inappropriate
venue for that) of an offline/buildable documentation as a proper bug
report, and also kind enough to be willing to spend some of your
volunteer time to fix it. Beancount's is some of the best documentation
I've seen around in the Free Software projects I use daily, and that
technical bit will enable some of us to peruse it even more effectively.
Thank you!

(If you prefer to have this as a proper bug report in the BTS, so that
we can coordinate to implement the needed bits, just let me know.)

Martin Blais

unread,
Sep 24, 2017, 3:33:27 AM9/24/17
to Beancount
For those who would like to have a shot at automating the conversion of Beancount's Google Docs files to Markdown - a topic which fills the hearts of some with great passion - here's a snapshot of all the documents exported to all the available formats:

The files were exported with this script:
Along with the exported files, I also ran pandoc with native output where possible.

I took some notes on the conversion in the past:

It seems like one may have to source from more than one export in order to obtain all the necessary bits to make a nice conversion.
Most difficult is that all the formats seem to lose the indentation of the "code" (Beancount source) examples.
(I think it should be possible to automatically reindent it with code.)



--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.
To post to this group, send email to bean...@googlegroups.com.

Stefano Zacchiroli

unread,
Oct 30, 2017, 9:38:30 AM10/30/17
to bean...@googlegroups.com
Heya,

On Sun, Sep 24, 2017 at 03:33:03AM -0400, Martin Blais wrote:
> here's a snapshot of all the documents exported to all the available
> formats: http://furius.ca/tmp/beancount/beancount-docs-exported.tar.gz

Thanks for this, very useful.

I've started looking into automatically converting to something that
Sphinx would like to produce good output. Question about your findings:

> I took some notes on the conversion in the past:
> https://bitbucket.org/blais/beancount/src/22be0f233d079c14dc727d54378d21164db04cdf/experiments/docs/convert/compare_download_formats.txt
>
> It seems like one may have to source from more than one export in order to
> obtain all the necessary bits to make a nice conversion.
> Most difficult is that all the formats seem to lose the indentation of the
> "code" (Beancount source) examples.
> (I think it should be possible to automatically reindent it with code.)

Docx output seems indeed to be the most rich output option from Google
Docs. But AFAICT it does retain the needed spacing in Beancount code
snippets. Here's an example from the rounding precision proposal
document:

<w:t xml:space="preserve">2014-05-06 * “Buy mutual fund”</w:t>
<w:br w:type="textWrapping"/>
<w:t xml:space="preserve"> Assets:Investments:RGXGX 4.278 RGAGX {53.21 USD} </w:t>
<w:br w:type="textWrapping"/>
<w:t xml:space="preserve"> Assets:Investments:Cash -227.6324 USD</w:t>
<w:br w:type="textWrapping"/>
<w:t xml:space="preserve"> Expenses:Commissions 9.95 USD</w:t>

which corresponds to:

2014-05-06 * “Buy mutual fund”
Assets:Investments:RGXGX 23.45 RGAGX {42.6439 USD}
Assets:Investments:Cash -1000 USD

When reading docx *pandoc* does indeed strip those spaces,
unfortunately, so one can't simply rely on pandoc for a docx -> rst
conversation, but the information seems to be there in the docx.

I'll give this path a try, but please let me know if you're aware that
I'm missing something here!

Martin Blais

unread,
Nov 6, 2017, 1:20:01 AM11/6/17
to Beancount
This is a good observation, I hadn't noticed this myself. This is great.
I think it should be possible to combine the output from pandoc and splice in the code examples extracted from a custom (Python) script.
Thank you for this,

Martin Blais

unread,
Feb 20, 2018, 12:07:26 AM2/20/18
to Martin Blais, Beancount
BTW, I just made some manner of progress toward this.

I went about this in a bit of a roundabout way, I wrote a script that extracts the indented code blocks from the Docs to docx conversion, and inserts them into the docx to rst conversion output (done with Pandoc, which strips the indentation on those blockquotes). It's not perfect, but it's definitely readable, there are occasional mis-indent but in few of the code blocks.

(The right way to do all this would be to change Pandoc so that it doesn't strip the whitespace on those blocks, and I started that way but ended up going around in circles, my knowledge of Haskell isn't too amazing.)

Anyhow, I'll try to finish this and convert all the docs to rst at some point.

Martin Michlmayr

unread,
Mar 10, 2018, 6:43:52 PM3/10/18
to bean...@googlegroups.com, Martin Blais
* Martin Blais <bl...@furius.ca> [2018-02-20 00:07]:
> Anyhow, I'll try to finish this and convert all the docs to rst at some
> point.

Once the rst documents exist, are you going to accept pull requests
with changes against the rst (and apply them to your canonical source)
or how should people interested in working on docs submit changes?

--
Martin Michlmayr
http://www.cyrius.com/

Martin Blais

unread,
Mar 11, 2018, 12:56:32 PM3/11/18
to Martin Michlmayr, Beancount, Martin Blais
Not planning to move to rst as an input format.
I still would use GDocs as input; just request comment access and I'll accept liberally. 
The idea would be to fully automate the conversion.
(The only reason I made the docs RO was to avoid the numerous and frequent fingerfarts.)

Martin Blais

unread,
Mar 14, 2018, 1:08:29 AM3/14/18
to Beancount, Martin Michlmayr
I just cleaned up the hacky conversion code a bit.

If anybody would like to have a go at completing this, the source is here:
https://bitbucket.org/blais/beancount/src/tip/experiments/docs_rst/?at=default

Instead of running the download_docs.py script, which might require a Google API token, I made an archive of what it downloads here:

See the Makefile.
What remains to be done is
- Check that the output converts nicely
- If not, find ways to automatedly fix it during the conversion, I'm not 100% sure that's possible (I'm hoping)
- Integrate it in Dominik Aumayr's static docs and look at the converted text
- Eventually I'd like to merge that into Beancount itself and maintain it (with Dominik's permission).


Dominik Aumayr

unread,
Mar 16, 2018, 9:49:06 AM3/16/18
to bean...@googlegroups.com
- Eventually I'd like to merge that into Beancount itself and maintain it (with Dominik's permission).

Permission hereby granted :-)
--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.

To post to this group, send email to bean...@googlegroups.com.

Martin Blais

unread,
Mar 24, 2018, 12:35:47 AM3/24/18
to Beancount
Thx Dominik.

BTW, here's what the current automated conversion results looks like in your static skeleton:

This was entirely produced by the code I wrote here, no manual changes:
It's incomplete, but you can see how pretty darn close it is (it's readable, but flawed).

Quick comments:
- I haven't copied all the docs, just the ones you had linked in, it would be easy to include more in the structure
- Some - but not all - of the code blocks are erroneous, they have an extra duplicated unindented last line (probably a bug in convert_docs.py)
- Some of the **bold** and *italic* strings don't render as such, I don't know why (input looks right)
- Some of the list items somehow have their indentation badly converted by Pandoc
- The index on the left shows sections for the entire set of documents - this is too much, should show sections for each document only

I think post-processing the rst from Pandoc it would be possible to fix all these things to make it a fully automated conversion.




To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.

To post to this group, send email to bean...@googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.

To post to this group, send email to bean...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/9CBA7B3A-292A-4803-BD76-C8C4B1AA90B2%40aumayr.name.

Dominik Aumayr

unread,
Mar 24, 2018, 6:15:52 AM3/24/18
to bean...@googlegroups.com
This looks great! Thanks for working on this! :)

> It's incomplete, but you can see how pretty darn close it is (it's readable, but flawed).

Except for the code blocks (they should be in a monospaced font, as otherwise it would be confusing for the reader), and the sidebar (can be configured in Sphinx, afaik), this looks as pretty as I hoped for. How much work do you plan to put in until you "release" this? (As it looks like not much is needed for "release-readyness", imho.)
>> To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
>> To post to this group, send email to bean...@googlegroups.com.
>> To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/CAK21%2BhNTudNTXeuBaATdfFCk0q2_wV3HJd%3DZ8ZV5K3cgVm3Org%40mail.gmail.com.
>> For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the Google Groups "Beancount" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
> To post to this group, send email to bean...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/9CBA7B3A-292A-4803-BD76-C8C4B1AA90B2%40aumayr.name.
>
> For more options, visit https://groups.google.com/d/optout.
>
>
> --
> You received this message because you are subscribed to the Google Groups "Beancount" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
> To post to this group, send email to bean...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/CAK21%2BhNx0Y8xofVqWE%2B07RfaHF19nLPQKjMwBrMnGNuGbF%2B5Kw%40mail.gmail.com.

Stefano Zacchiroli

unread,
Mar 24, 2018, 12:33:36 PM3/24/18
to bean...@googlegroups.com
On Sat, Mar 24, 2018 at 12:35:23AM -0400, Martin Blais wrote:
> BTW, here's what the current automated conversion results looks like in
> your static skeleton:
> http://furius.ca/tmp/beancount-docs/

This is just ... wow ... amazing work Martin, thanks for doing this!

My only comment (in the same spirit of Dominik's point about lowering
the barrier for contributions) is to document in the doc itself how to
contribute.

I understand you want comments/edit suggestion via Google Docs. And each
sphinx document already points to the corresponding Google Docs origin.
I suggest prefixing each link with something like "to suggest edits to
this document go to ...". And I'm assuming you will re-enable
suggestions on the Google Docs once the sphinx documents will be
advertised as the main entry points for users, right?

Cheers

Martin Blais

unread,
Mar 25, 2018, 1:05:06 PM3/25/18
to Beancount
On Sat, Mar 24, 2018 at 12:33 PM, Stefano Zacchiroli <za...@upsilon.cc> wrote:
On Sat, Mar 24, 2018 at 12:35:23AM -0400, Martin Blais wrote:
> BTW, here's what the current automated conversion results looks like in
> your static skeleton:
> http://furius.ca/tmp/beancount-docs/

This is just ... wow ... amazing work Martin, thanks for doing this!

My only comment (in the same spirit of Dominik's point about lowering
the barrier for contributions) is to document in the doc itself how to
contribute.

I understand you want comments/edit suggestion via Google Docs. And each
sphinx document already points to the corresponding Google Docs origin.
I suggest prefixing each link with something like "to suggest edits to
this document go to ...".

Adding a link at the top of echo doc is a good idea.

 
And I'm assuming you will re-enable
suggestions on the Google Docs once the sphinx documents will be
advertised as the main entry points for users, right?

I haven't found a solution for fat fingers yet, so probably not.

(If you'd like to comment on anything, make a request via the pulldown menu, I usually respond to those within the day.)



Cheers
--
Stefano Zacchiroli . za...@upsilon.cc . upsilon.cc/zack . . o . . . o . o
Computer Science Professor . CTO Software Heritage . . . . . o . . . o o
Former Debian Project Leader & OSI Board Director  . . . o o o . . . o .
« the first rule of tautology club is the first rule of tautology club »

--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.
To post to this group, send email to bean...@googlegroups.com.

Martin Blais

unread,
Mar 25, 2018, 1:06:06 PM3/25/18
to Beancount
On Sat, Mar 24, 2018 at 6:15 AM, Dominik Aumayr <dom...@aumayr.name> wrote:
This looks great! Thanks for working on this! :)

> It's incomplete, but you can see how pretty darn close it is (it's readable, but flawed).

Except for the code blocks (they should be in a monospaced font, as otherwise it would be confusing for the reader), and the sidebar (can be configured in Sphinx, afaik), this looks as pretty as I hoped for.

Glad you like it. 

 
How much work do you plan to put in until you "release" this? (As it looks like not much is needed for "release-readyness", imho.)

I was hoping to fix the various formatting issues.


 
>> To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.

>> To post to this group, send email to bean...@googlegroups.com.
>> To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/CAK21%2BhNTudNTXeuBaATdfFCk0q2_wV3HJd%3DZ8ZV5K3cgVm3Org%40mail.gmail.com.
>> For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the Google Groups "Beancount" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.

> To post to this group, send email to bean...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/9CBA7B3A-292A-4803-BD76-C8C4B1AA90B2%40aumayr.name.
>
> For more options, visit https://groups.google.com/d/optout.
>
>
> --
> You received this message because you are subscribed to the Google Groups "Beancount" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.

> To post to this group, send email to bean...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.

To post to this group, send email to bean...@googlegroups.com.

Martin Michlmayr

unread,
May 9, 2018, 8:29:15 AM5/9/18
to bean...@googlegroups.com
* Martin Blais <bl...@furius.ca> [2018-03-24 00:35]:
> BTW, here's what the current automated conversion results looks like in
> your static skeleton:
> http://furius.ca/tmp/beancount-docs/

http://furius.ca/tmp/beancount-docs/users/installation.html has some
formatting issues. It seems ReST links are created for links in
verbatim elements, see e.g. section "Where to Get It"

What's needed to make these docs official?

I'm happy to go through everything and flag issues.
--
Martin Michlmayr
https://www.cyrius.com/

Martin Blais

unread,
May 9, 2018, 11:29:06 PM5/9/18
to Beancount
On Wed, May 9, 2018 at 8:29 AM, Martin Michlmayr <t...@cyrius.com> wrote:
* Martin Blais <bl...@furius.ca> [2018-03-24 00:35]:
> BTW, here's what the current automated conversion results looks like in
> your static skeleton:
> http://furius.ca/tmp/beancount-docs/

http://furius.ca/tmp/beancount-docs/users/installation.html has some
formatting issues.  It seems ReST links are created for links in
verbatim elements, see e.g. section "Where to Get It"

What's needed to make these docs official?

There are number of quirks like that.
Finding a way - even a kludgey solution - to fixup all those quirks automatically is what I'm looking for.
Your contribution in that department would be highly appreciated.
I would suggest first making sure you can run the whole conversion process yourself, and then if  you want, add some Python to address the quirks one by one, patches welcome.
The source code is here:

Please ignore the docs-related scrips under tools/, I need to remove them.


 
I'm happy to go through everything and flag issues.

That sounds great!
There's a "docs" component for tickets; make sure to file it under that rubric.


 
--
Martin Michlmayr
https://www.cyrius.com/
--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscribe@googlegroups.com.
To post to this group, send email to bean...@googlegroups.com.

Oon-Ee Ng

unread,
Nov 27, 2018, 10:24:05 PM11/27/18
to bean...@googlegroups.com
On Thu, May 10, 2018 at 11:29 AM Martin Blais <bl...@furius.ca> wrote:
On Wed, May 9, 2018 at 8:29 AM, Martin Michlmayr <t...@cyrius.com> wrote:
* Martin Blais <bl...@furius.ca> [2018-03-24 00:35]:
> BTW, here's what the current automated conversion results looks like in
> your static skeleton:
> http://furius.ca/tmp/beancount-docs/

http://furius.ca/tmp/beancount-docs/users/installation.html has some
formatting issues.  It seems ReST links are created for links in
verbatim elements, see e.g. section "Where to Get It"

What's needed to make these docs official?

There are number of quirks like that.
Finding a way - even a kludgey solution - to fixup all those quirks automatically is what I'm looking for.
Your contribution in that department would be highly appreciated.
I would suggest first making sure you can run the whole conversion process yourself, and then if  you want, add some Python to address the quirks one by one, patches welcome.
The source code is here:

Please ignore the docs-related scrips under tools/, I need to remove them.

Can I assume this is on-hold/pause currently?

I'm finally getting round to implementing some imports after using beancount for more than a year, and I think the 'Importing External Data' section could use some sprucing up, wondering how I would suggest changes now that the Google Doc suggest edits route is no longer open. 

Martin Blais

unread,
Nov 28, 2018, 11:00:24 PM11/28/18
to bean...@googlegroups.com
On Tue, Nov 27, 2018 at 10:24 PM Oon-Ee Ng <ngoone...@gmail.com> wrote:
On Thu, May 10, 2018 at 11:29 AM Martin Blais <bl...@furius.ca> wrote:
On Wed, May 9, 2018 at 8:29 AM, Martin Michlmayr <t...@cyrius.com> wrote:
* Martin Blais <bl...@furius.ca> [2018-03-24 00:35]:
> BTW, here's what the current automated conversion results looks like in
> your static skeleton:
> http://furius.ca/tmp/beancount-docs/

http://furius.ca/tmp/beancount-docs/users/installation.html has some
formatting issues.  It seems ReST links are created for links in
verbatim elements, see e.g. section "Where to Get It"

What's needed to make these docs official?

There are number of quirks like that.
Finding a way - even a kludgey solution - to fixup all those quirks automatically is what I'm looking for.
Your contribution in that department would be highly appreciated.
I would suggest first making sure you can run the whole conversion process yourself, and then if  you want, add some Python to address the quirks one by one, patches welcome.
The source code is here:

Please ignore the docs-related scrips under tools/, I need to remove them.

Can I assume this is on-hold/pause currently?

I haven't worked on it.
Too busy.


I'm finally getting round to implementing some imports after using beancount for more than a year, and I think the 'Importing External Data' section could use some sprucing up, wondering how I would suggest changes now that the Google Doc suggest edits route is no longer open. 

I opened up for comments for you. If you need comment access on any other doc, let me know. 
Thank you,



--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.

To post to this group, send email to bean...@googlegroups.com.

llpa...@gmail.com

unread,
Feb 15, 2019, 2:03:27 PM2/15/19
to Beancount
Google recently released the API for Docs [1]. This should make the export process easier. Has anyone looked at it? Is anyone working on this?

Martin Blais

unread,
Feb 17, 2019, 3:52:03 PM2/17/19
to Beancount
That looks nice and promising indeed, you get access to their structure of the document:
Thanks for sending a pointer to this. I hadn't noticed this release.

I haven't done any work with this yet. 
It looks like it could potentially work.





To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/0df8f70c-45e3-4c70-8bea-dec310694b85%40googlegroups.com.

Martin Blais

unread,
Feb 17, 2019, 4:05:04 PM2/17/19
to Martin Blais, Beancount
I just tried it, this API provides enough detail to do a much better job at converting to Markdown.
I could easily and reliably identify code blocks with it.

Martin Blais

unread,
Feb 17, 2019, 10:20:17 PM2/17/19
to Beancount
I really think this could work.
I've downloaded the JSONs for all the current Beancount docs here:
There's a little Python script in there you can just run, I hacked on this for a half hour, just kicking the tires.
If anyone would like to have a go at it, this is a good place to start.
It will run its incomplete parser on all the docs in the current dir.
e.g. run it like this:
./convert_docs_json_to_markdown.py .
I think there's enough information in the JSON files to make a really good conversion.


Kirill Goncharov

unread,
Jun 26, 2019, 9:07:52 AM6/26/19
to Beancount
I wrote another script for parsing Google Docs. If anyone interested, the result is at https://github.com/xuhcc/beancount-docs/blob/master/docs/00_beancount_documentation.md

Uwe Ziegenhagen

unread,
Jun 26, 2019, 4:42:41 PM6/26/19
to bean...@googlegroups.com
That looks pretty good. I used Pandoc to convert the MD files to PDF via xelatex, find the result here:

http://uweziegenhagen.de/converted.pdf

Not perfect, but for a quick & dirty approach it is fine.

Are there any plans to switch to the github markdown for the documentation instead of using Google Docs?

Uwe

Am Mi., 26. Juni 2019 um 15:07 Uhr schrieb Kirill Goncharov <kdgon...@gmail.com>:
I wrote another script for parsing Google Docs. If anyone interested, the result is at https://github.com/xuhcc/beancount-docs/blob/master/docs/00_beancount_documentation.md

--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
To post to this group, send email to bean...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/13773d0b-85b3-4265-86e2-c1e5b356f3d2%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.


--
Dr. Uwe Ziegenhagen

Kirill Goncharov

unread,
Aug 2, 2019, 5:18:20 AM8/2/19
to Beancount
Docs now available at GitHub Pages: https://xuhcc.github.io/beancount-docs/

среда, 26 июня 2019 г., 16:07:52 UTC+3 пользователь Kirill Goncharov написал:

Red S

unread,
Aug 3, 2019, 3:21:49 AM8/3/19
to Beancount
This is terrific. It loads so much faster than google docs, doesn't need an app/sign in. Thank you for doing this.

May I know what you had in mind for the update policy? How up-to-date with the originals will this be?

Thanks again!

Kirill Goncharov

unread,
Aug 3, 2019, 6:31:30 AM8/3/19
to Beancount
I'll update it regularly, maybe once in a week. Source files in markdown format are generated automatically from Google documents by a script.

суббота, 3 августа 2019 г., 10:21:49 UTC+3 пользователь Red S написал:

Stefano Zacchiroli

unread,
Aug 3, 2019, 6:42:10 AM8/3/19
to bean...@googlegroups.com
On Fri, Aug 02, 2019 at 02:18:20AM -0700, Kirill Goncharov wrote:
> Docs now available at GitHub Pages: https://xuhcc.github.io/beancount-docs/

Thanks a lot for doing this, it's awesome !

Daniele Nicolodi

unread,
Aug 5, 2019, 1:49:38 PM8/5/19
to bean...@googlegroups.com
On 03-08-2019 04:42, Stefano Zacchiroli wrote:
> On Fri, Aug 02, 2019 at 02:18:20AM -0700, Kirill Goncharov wrote:
>> Docs now available at GitHub Pages: https://xuhcc.github.io/beancount-docs/
>
> Thanks a lot for doing this, it's awesome !

Indeed, I like it much better than the Google Docs version. Thank you! I
noticed a couple of minor glitches in the conversion. I'll report them
when I'll have a bit more time.

I think a theme similar to the Read The Docs one makes reading long
sectioned documents a bit easier. Have you considered something like it?

It would also be cool to integrate this with API documentation via
Sphinx. Is that possible with the Markdown source format or would it
need to be reST?

Thank you.

Cheers,
Dan

Kirill Goncharov

unread,
Aug 5, 2019, 2:38:51 PM8/5/19
to Beancount
>I think a theme similar to the Read The Docs one makes reading long
sectioned documents a bit easier. Have you considered something like it?

I don't know if such a theme exists. By default, GitHub supports these themes: https://pages.github.com/themes/, but they all are different from Read the Docs.

>It would also be cool to integrate this with API documentation via
Sphinx. Is that possible with the Markdown source format or would it
need to be reST?

Yes, it is possible. We can also configure pandoc to output rst files.

понедельник, 5 августа 2019 г., 20:49:38 UTC+3 пользователь Daniele Nicolodi написал:

Martin Blais

unread,
Aug 6, 2019, 9:32:15 PM8/6/19
to Beancount
Very nice conversion.
Nice work on fixing the code block formatting by converting the source...
If you would like I could trigger conversions on major/minor releases and check in the markdown next to the source code.





--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/d7c92b21-365b-46ac-860d-ddf8acde87c7%40googlegroups.com.

Kirill Goncharov

unread,
Aug 7, 2019, 8:32:28 AM8/7/19
to Beancount
Yes, that would be awesome! We can then similarly configure https://github.com/beancount/beancount repo to serve markdown documents using the Github Pages service.

среда, 7 августа 2019 г., 4:32:15 UTC+3 пользователь Martin Blais написал:
To unsubscribe from this group and stop receiving emails from it, send an email to bean...@googlegroups.com.

Martin Michlmayr

unread,
May 11, 2020, 2:32:50 AM5/11/20
to bean...@googlegroups.com
* Kirill Goncharov <kdgon...@gmail.com> [2019-08-02 02:18]:
> Docs now available at GitHub Pages: https://xuhcc.github.io/beancount-docs/

This is very impressive.

But afaict it doesn't have the API reference that Dominik's version
has.

His uses Sphinx whereas you use MkDocs.

Is there any chance we could agree one one solution and improve that
together?

(I noticed some formatting issues in the API reference, i.e. in the
docstrings.)

Martin Michlmayr

unread,
May 11, 2020, 3:13:59 AM5/11/20
to bean...@googlegroups.com
* Kirill Goncharov <kdgon...@gmail.com> [2019-08-02 02:18]:
> Docs now available at GitHub Pages: https://xuhcc.github.io/beancount-docs/

I found a number of formatting issues but they are problems in the
Google docs (I left some comments).

This looks really good. Thanks for working on this!

Kirill Goncharov

unread,
May 11, 2020, 7:52:29 AM5/11/20
to Beancount
MkDocs has several plugins that could build documentation from docstrings.

I tried mkdocstrings (https://github.com/pawamoy/mkdocstrings). It doesn't support readthedocs theme and its parser has issues, so I was not able to add documentation for all modules: https://xuhcc.github.io/beancount-docs/api_reference/index.html

But it is in active development and hopefully these issues will be resolved soon.

Martin Blais

unread,
May 11, 2020, 9:56:11 AM5/11/20
to Beancount
Martin: Yes, Kirill's docs are awesome.
You've got some newfound Kix power on the Beancount docs; use them wisely.



--
You received this message because you are subscribed to the Google Groups "Beancount" group.
To unsubscribe from this group and stop receiving emails from it, send an email to beancount+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/20200511071351.GA19139%40jirafa.cyrius.com.

Kirill Goncharov

unread,
May 11, 2020, 3:37:53 PM5/11/20
to Beancount
Update: All major issues were resolved!

Martin Michlmayr

unread,
May 11, 2020, 10:52:12 PM5/11/20
to bean...@googlegroups.com
* Kirill Goncharov <kdgon...@gmail.com> [2020-05-11 12:37]:
> Update: All major issues were resolved!
>
> Full API reference now available at
> https://xuhcc.github.io/beancount-docs/api_reference/index.html

Impressive speed! Thanks to you and your responsive upstream!
Reply all
Reply to author
Forward
0 new messages