Closed maxsnew closed 8 years ago
Sounds handy. Basically uses elm-doc
but generates the html from it :)
I think this makes sense. It also seems like this does not belong in elm-doc
because it should be style agnostic.
K, I'll try implementing this today.
Just want to add a variation on this idea that came up talking with @agazso today.
What if elm-get docs
started up an instance of the catalog that was specific to your particular project. You'd only see the docs for the stuff you have installed.
@evancz @ddrone I'm looking back into this now, I think it would mostly involve moving the Generate modules into the elm-get part of the repo. Should I target master and we'll merge that into dependencies or target dependencies and eventually merge it and the new features together into master? Doing it separately off of the master branch would be preferable but I don't know if that would cause a lot of headaches later.
I don't think we should do it right now. The ideal situation is that the docs viewer is a single Elm file that works on JSON files with a particular format. This is ideal both for the website and for this feature. So I think it'd be best to focus on dynamic Markdown rendering which would make this much simpler.
I think trying to use the existing stuff will lead to a bad solution that would eventually get torn out.
Is that work happening somewhere? I really would just like this feature for myself so I can do things like test my documentation beforehand or post docs for IO and Elm-Test which aren't on the public library.
On Wednesday, September 3, 2014, Evan Czaplicki notifications@github.com wrote:
I don't think we should do it right now. The ideal situation is that the docs viewer is a single Elm file that works on JSON files with a particular format. This is ideal both for the website and for this feature. So I think it'd be best to focus on dynamic Markdown rendering which would make this much simpler.
I think trying to use the existing stuff will lead to a bad solution that would eventually get torn out.
— Reply to this email directly or view it on GitHub https://github.com/elm-lang/elm-get/issues/20#issuecomment-54370095.
-Max Stewart New
It is a long way off. The shortest path I see is adding a few features to elm-html, allowing dependencies in the Catalog, and finally releasing a markdown library that is connected to elm-html.
Can you do it in your own fork if you absolutely need it right this second?
I want to set up a design doc for this project so we can specify the API and responsibilities more formally. I think we should outline things there before going and adding this.
Oh, also, please don't touch the master branch for now! I'm trying to release 0.13 and having changes in master branches of any projects that I don't know about is not ideal.
Yeah I guess I'll just do it on my own branch for now.
On Wednesday, September 3, 2014, Evan Czaplicki notifications@github.com wrote:
Oh, also, please don't touch the master branch for now! I'm trying to release 0.13 and having changes in master branches of any projects that I don't know about is not ideal.
— Reply to this email directly or view it on GitHub https://github.com/elm-lang/elm-get/issues/20#issuecomment-54371054.
-Max Stewart New
I just added you to a design doc for this kind of thing. Let's write it out there so there is some coherent record of what we want to achieve with this tool.
I think the best way to go is to work from the dependencies branch because that will be the base for the next version of elm-get. The next time this gets released though, we will need to have done this.
So this could maybe be the new "elm doc" rather than "elm get doc"? Makes sense to me
On Wednesday, September 3, 2014, Evan Czaplicki notifications@github.com wrote:
I just added you to a design doc for this kind of thing. Let's write it out there so there is some coherent record of what we want to achieve with this tool.
I think the best way to go is to work from the dependencies branch because that will be the base for the next version of elm-get. The next time this gets released though, we will need to have done this https://gist.github.com/evancz/d32d3cda89c6cfb01428.
— Reply to this email directly or view it on GitHub https://github.com/elm-lang/elm-get/issues/20#issuecomment-54371688.
-Max Stewart New
What if the feature was like this:
You run elm-package preview
in the root of your project. It starts a server on localhost:8000 that lets you navigate around really easily.
Another way to think of generating docs is "spit out some HTML files" which I think is actually a special case of what people are interested in with this feature. I can imagine someone wanting to host these files on a server they own, but I think that's not the problem we are trying to solve.
Our goal is "let me preview docs before I publish" and I think the local server is the most pleasant route.
Why do you need a server at all though? You're just navigating between a bunch of HTML files on your local file system so opening one in the browser should just work
On Wednesday, September 3, 2014, Evan Czaplicki notifications@github.com wrote:
What if the feature was like this:
You run elm-package preview in the root of your project. It starts a server on localhost:8000 that lets you navigate around really easily.
Another way to think of generating docs is "spit out some HTML files" which I think is actually a special case of what people are interested in with this feature. I can imagine someone wanting to host these files on a server they own, but I think that's not the problem we are trying to solve.
Our goal is "let me preview docs before I publish" and I think the local server is the most pleasant route.
— Reply to this email directly or view it on GitHub https://github.com/elm-lang/elm-get/issues/20#issuecomment-54372759.
-Max Stewart New
Another variation is to have this:
Run elm-package docs
in the root of your project. It starts a server on localhost:800 that has documentation for all of the packages used by your project, including documentation of your stuff.
This gives an entirely offline way to browse docs.
Opening individual HTML files that may or may not link together nicely feels very 1990s
If all of the links are relative they would link together nicely just fine wouldn't they?
On Wednesday, September 3, 2014, Evan Czaplicki notifications@github.com wrote:
Opening individual HTML files that may or may not link together nicely feels very 1990s
— Reply to this email directly or view it on GitHub https://github.com/elm-lang/elm-get/issues/20#issuecomment-54373172.
-Max Stewart New
You don't necessarily need a server, but if the goal is "let people browse and preview docs" then we should not be trying to minimize the work we do at the expense of providing a less nice experience.
How does a/b/c link to x/y/z?
Doing /x/y/z would mess up on any platform I know of. I guess you could always do ../../../x/y/z but I think that's besides the point.
I don't see how that's beside the point, the user doesn't care that they're relative links, if we're putting them all in a docs directory then it's totally safe On Sep 3, 2014 5:53 PM, "Evan Czaplicki" notifications@github.com wrote:
How does a/b/c link to x/y/z?
Doing /x/y/z would mess up on any platform I know of. I guess you could always do ../../../x/y/z but I think that's besides the point.
— Reply to this email directly or view it on GitHub https://github.com/elm-lang/elm-get/issues/20#issuecomment-54373462.
Besides the point in that it may be technically possible, but I don't think that means static files is the best solution. To me, navigating in browser just like the website is a superior experience. Digging through directories is not something I think I'd be super excited about.
Can we do some design docs on this? Like, how could this integrate with Elm Reactor? Perhaps that's the ideal way to browse docs? What are the possible ways we can achieve our goals? What are the tradeoffs of each approach? What exactly are the concrete goals of this in the first place?
Why wouldn't static files be just like navigating in a browser? It's just a matter of opening the topmost index.html
file that was generated and the rest is a matter of navigating in the browser. Those static files can look as nice as you like, no need for making it feel like the 90s.
AFAIK, a very popular documentation generation system is Doxygen, which generates static HTML pages (admittedly ugly ones that looks like they're from the 90s :P) that work just fine in a browser without needing a local server.
(Of course there are many documentation generators, but this happens to be a versatile one that I know and apparently Haddock was influenced by Doxygen. )
I think the main benefits of static pages are:
I talked through this with someone and it seems to make sense to do static files. I think they should be generated by a separate elm-doc tool, meaning the view code should move over to the compiler. I don't want to work on this right new because 0.13 is coming soon, but I'll start transferring stuff over when I pick up where @ddrone left off with elm-get.
Any news on this?
Finally this exists http://package.elm-lang.org/help/docs-preview thanks to @burabure!
I would still like to have something like this. Basically a way to view the Elm docs offline
I would also like to have this. Especially as elm-make --docs=documentation.json seems to return a file containing just the two characters []...
I think it only generates docs for modules in the exposed-modules list in elm-package.json. Try adding them there On Thu, Jun 30, 2016 at 8:54 AM Deimos28 notifications@github.com wrote:
I would also like to have this. Especially as elm-make --docs=documentation.json seems to return a file containing just the two characters []...
— You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub https://github.com/elm-lang/elm-package/issues/20#issuecomment-229703075, or mute the thread https://github.com/notifications/unsubscribe/AAAcrd0PCKAKgAU4bArWbVfiU7nzwjMzks5qQ-bQgaJpZM4BZCA5 .
Thanks! I'll try that. Le 30 juin 2016 6:27 PM, "Pete Vilter" notifications@github.com a écrit :
I think it only generates docs for modules in the exposed-modules list in elm-package.json. Try adding them there On Thu, Jun 30, 2016 at 8:54 AM Deimos28 notifications@github.com wrote:
I would also like to have this. Especially as elm-make --docs=documentation.json seems to return a file containing just the two characters []...
— You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub < https://github.com/elm-lang/elm-package/issues/20#issuecomment-229703075>, or mute the thread < https://github.com/notifications/unsubscribe/AAAcrd0PCKAKgAU4bArWbVfiU7nzwjMzks5qQ-bQgaJpZM4BZCA5
.
— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/elm-lang/elm-package/issues/20#issuecomment-229712522, or mute the thread https://github.com/notifications/unsubscribe/ADYDvODLfX5CaJprz4S1wO6zfx2w0xozks5qQ-5lgaJpZM4BZCA5 .
I'm not sure if this is a new feature or not. Is there a way to build all of the docs to see what the site will look like when it gets published to library.elm-lang.org? I've messed up docs a few times but I didn't know how to see what they would look like until I publish, at which point I can fix and repush.
I'm imagining a feature where I could run
elm-get docs
in my project and get a directory calleddocs
or something that has the pages generated for the website.