Arc Forumnew | comments | leaders | submitlogin
2 points by rocketnia 3903 days ago | link | parent

Sorry, I think I was mistaken. If the hypertext reference is generated from docstrings at all, I don't see how. Even if there were a tool, it would require some manual work afterward to place the definitions into appropriate categories.


2 points by akkartik 3892 days ago | link

I've updated the docs. I've also taken out the help/ dir entirely and inlined all the docstrings into arc.arc and elsewhere.

I'm still unsure how to organize the arcfn reference guide at http://arclanguage.github.io/ref so that we remember to update it when we make changes, and so it's convenient to update the website. Another complication is that the arclanguage account contains multiple dialects of arc with subtle differences, and the current organization of documentation is misleadingly monolithic. Any suggestions to fix this most appreciated. (We discussed this previously a year ago: http://www.arclanguage.org/item?id=17774)

-----

4 points by akkartik 3890 days ago | link

Ok, I've taken a stab at a minimal-effort reorg of http://arclanguage.github.io. Before: http://i.imgur.com/hCpkFyj.png. After: http://i.imgur.com/KvwrEg9.png. It's more clear now that tryarc and /ref/ are for arc 3.1. Anarki is currently just more capable at the commandline.

-----

2 points by evanrmurphy 3890 days ago | link

Makes the Arc 3.1 vs. Anarki distinction much clearer to a new visitor. Nice job, akkartik.

-----

2 points by thaddeus 3891 days ago | link

Something like marginalia[1] might prove to be better than the arcfn docs. Not only because the docs would be fully integrated with the source code, but because it would also solve the multiple dialects problem. i.e. If some given code can be tagged with a dialect name then automation could also apply a dialect filter.

Of course this would probably be quite a bit of an undertaking.

1.http://gdeer81.github.io/marginalia/ & https://github.com/gdeer81/marginalia

-----

2 points by akkartik 3891 days ago | link

The crux is colocating the rendered docs online with the repo. Would marginalia help us use github's hosting with github pages, managing branches, etc? If it does I think I'd be willing to go on a significant undertaking.

-----

2 points by thaddeus 3891 days ago | link

Marginalia is clojure specific so I expect it will not help other than to provide ideas.

To create an arc equivalent you probably need build an arc library which provides some code inspection/dissection capabilities and ideally also be able to attach metadata to any given function or macro. With such a library you then build a script to auto generate the docs.

As for GitHub syncing; well no, I'm guessing users would need to trigger the script and then check in the updated docs.

This is still better for a few reasons...1. developers can generate docs, locally, that are in sync with the code base they are actually using (checked out or branched). 2. Even if the online docs gets out of sync for a while you're still only a script trigger away for updating all outstanding changes.

The alternative is what you just went through; having someone remind you to do the work manually as an after-thought, which I've only seen happen once.

-----