[HN Gopher] Doctree
___________________________________________________________________
Doctree
Author : tosh
Score : 84 points
Date : 2022-04-29 10:11 UTC (1 days ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| jitl wrote:
| I'm ecstatic that someone is building this.
|
| Figuring out sourcecode-to-apidocs for one language is annoying,
| and figuring it out in the context of multi-language monorepos is
| exhausting. Then on top of that, I want to fail the build if
| someone adds public APIs to a library and doesn't document them!
| Now I have to go back to all my doc generators and get some kind
| of metadata out of them??????? And what if I want to make my docs
| pretty, and link to each other across languages??????
| SFLSJHDFKJSDHKJF
|
| So, this is great. A small dream, coming true. Best of luck to
| y'all!
| mhh__ wrote:
| https://mir-algorithm.dpldocs.info/mir.ndslice.html is a D
| specific approach to something like this (it doesn't use the same
| approach as the builtin doc generator you get with the D
| compiler, e.g. everything appears in the docs just some things
| are noted as being undocumented)
| slimsag wrote:
| Whoa, wasn't expecting to see this on HN! I've only done a week
| of work on this, _super_ early stages - here are our plans for
| it:
|
| * 100% OSS tool, run locally on your machine (static Go binary)
| or use https://doctree.org (not online yet, plug in a repository
| name, get docs) - really want this to be a proper, useful FOSS
| tool.
|
| * Work with any language, based on tree-sitter.
|
| * Provide symbol-level search functionality.
|
| * Surface real-world usage examples automatically, probably based
| on some statistical analysis of how functions are commonly used
| in open source code via Sourcegraph API, similar to what
| https://codestat.dev is doing.
|
| Tech details (again, just a week in):
|
| * Go for backend, Elm for frontend
|
| * Indexers will be written in Go, use tree-sitter queries to
| produce a standard index schema which then gets served to Elm
| frontend for rendering.
| https://github.com/sourcegraph/doctree/blob/main/doctree/sch...
|
| Probably not worth trying out right now, but if you're interested
| in it we set up a Discord server for collaboration, etc.
|
| https://discord.com/invite/vqsBW8m5Y8
|
| Happy to answer any questions!
| brainbag wrote:
| I've been wanting this to exist for years, ever since using
| Elixir and the amazing first class doc support. I hope it is
| super successful!
| mountainriver wrote:
| I'm getting "server not found" when I click on the web page
| bradleyjkemp wrote:
| And it's not just DNS issues. The domain doesn't even seem to
| be registered: it's available for purchase...
|
| edit: No longer! Hopefully someone benevolent picked it up
| mdaniel wrote:
| Sweet, a phishing opportunity! | Welcome to
| the doctree.dev demo site! |--- | Enter your
| github oauth2 token to see it work
| devass wrote:
| Probably some developer misusing the .dev domain for their
| own personal test projects, yet again.
| HWR_14 wrote:
| You mean "some dev deciding to keep using the .dev for
| personal test projects, as was the standard before ICANN
| and Google took a standard community resource and
| privatized it, yet again"
| chrisseaton wrote:
| > as was the standard
|
| Which standard was that? I thought only example.com was
| special-cased?
| HWR_14 wrote:
| Before ICANN started auctioning off TLDs it was common
| practice to use .dev and .test (probably others that
| escape me).
|
| It wasn't formalized, but that doesn't really matter. It
| was well known and commonly done.
|
| In fact, it couldn't have been formalized, because the
| TLDs were limited and by definition any non standard TLD
| was for internal use only. It would make no sense to have
| a defined standard for an impossible situation.
| detaro wrote:
| > _In fact, it couldn 't have been formalized, because
| the TLDs were limited and by definition any non standard
| TLD was for internal use only._
|
| No, there never was any guarantee that the existing TLDs
| were all that would exist ever, so non-standard TLDs were
| just that: non-standard, undefined what happens to them.
| And you even provided a counter-example: .test _is_
| explicitly reserved by an internet standard to never be
| in public DNS and thus safe to use for testing purposes.
| my69thaccount wrote:
| https://github.com/basecamp/pow
|
| Pow used .dev and .test in the 2000s-2010s
| chrisseaton wrote:
| That's not a standard that's just someone using them.
| slimsag wrote:
| To be clear, we do own the domain. It was registered about ~7
| days ago. It's just not deployed yet.
| bradleyjkemp wrote:
| May want to double check that: domain data shows it was
| only registered today about an hour ago:
| https://client.rdap.org/?type=domain&object=doctree.dev
|
| It was definitely available to purchase when I commented
| slimsag wrote:
| ..huh, yep, you're right. That's.. super embarrassing and
| huge screw up on my part, uhg. I was 100% positive I
| submitted the order through Namecheap before pushing the
| repo up to GitHub _for this exact reason_ , and that it
| went through.. but yeah, looks like I didn't and we don't
| own it. :(
|
| Good news is we've got doctree.org, so will be using that
| instead. I've removed all references to the other domain.
|
| If it was a good samaritan, shoot me an email ->
| stephen@sourcegraph.com
| __ryan__ wrote:
| I love namecheap but I have walked away thinking I've
| completed an order to find that there's a second order
| confirmation screen numerous times.
| slimsag wrote:
| This was probably it.. luckily, it seems like it may have
| been a good samaritan from HN, they reached out to me
| just now. People here rock :)
| mdaniel wrote:
| Unless "tosh" is one of the project authors, I'd guess this was
| submitted to HN before an official launch. That is, I bet there
| are a _lot_ of broken links from the website field in GitHub
| projects, and the only reason you expected this one to work was
| because it made the front page of HN and was in sourcegraph 's
| GitHub org
| tosh wrote:
| found it via the author's tweet:
|
| https://twitter.com/slimsag/status/1519910761400741888
| beliu wrote:
| I'm helping with the doctree effort at Sourcegraph. Apologies,
| the site isn't actually up yet. This project is still very
| early stages and we wrote up the README to serve as a sort of
| launch spec that we could update in response to feedback we
| receive. We made the repo public so we could build in public
| but didn't expect it to receive this much attention this early!
|
| So sorry that the site isn't up yet. We'll update the README
| soon to reflect that. If folks are interested in trying out a
| _super early_ version, there's the Docker run command and if
| you'd like to help us realize this vision, please join our
| Discord! https://discord.gg/vqsBW8m5Y8
| rvieira wrote:
| Incidentally, I've been getting a lot of timeouts from .dev
| TLDs today.
| pizza wrote:
| Interesting - wonder if there's a way to combine this with fzf +
| some kind of html or e.g. markdown viewer to search and read docs
| straight in the terminal
| qbasic_forever wrote:
| If the docs are generated from comments in the code a simple
| ripgrep search of the source (with fzf or other integration)
| will find things just as well too. Hound is a nice little web
| UI that does this: https://github.com/hound-search/hound
| slimsag wrote:
| Since `doctree` will be a static Go binary you can run locally,
| the idea is to have a "get docs straight in the terminal" via
| the CLI in the future. But probably a little ways away from
| that since we're just a week into it!
___________________________________________________________________
(page generated 2022-04-30 23:00 UTC)