search

elm-lang / elm-package

Command line tool to share Elm libraries
BSD 3-Clause "New" or "Revised" License
214 stars 66 forks source link

New Feature: elm-get docs #20

Closed maxsnew closed 8 years ago

maxsnew commented 10 years ago

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 called docs or something that has the pages generated for the website.

Apanatshka commented 10 years ago

Sounds handy. Basically uses elm-doc but generates the html from it :)

evancz commented 10 years ago

I think this makes sense. It also seems like this does not belong in elm-doc because it should be style agnostic.

maxsnew commented 10 years ago

K, I'll try implementing this today.

evancz commented 10 years ago

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.

maxsnew commented 10 years ago

@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.

evancz commented 10 years ago

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.

maxsnew commented 10 years ago

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

evancz commented 10 years ago

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.

evancz commented 10 years ago

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.

maxsnew commented 10 years ago

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

evancz commented 10 years ago

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.

maxsnew commented 10 years ago

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

evancz commented 10 years ago

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.

maxsnew commented 10 years ago

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

evancz commented 10 years ago

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.

evancz commented 10 years ago

Opening individual HTML files that may or may not link together nicely feels very 1990s

maxsnew commented 10 years ago

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

evancz commented 10 years ago

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.

evancz commented 10 years ago

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.

maxsnew commented 10 years ago

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.

evancz commented 10 years ago

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?

evancz commented 10 years ago

The design doc I started is here.

Apanatshka commented 10 years ago

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:

evancz commented 10 years ago

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.

wetmore commented 9 years ago

Any news on this?

evancz commented 8 years ago

Finally this exists http://package.elm-lang.org/help/docs-preview thanks to @burabure!

amcsi commented 8 years ago

I would still like to have something like this. Basically a way to view the Elm docs offline

Deimos28 commented 8 years ago

I would also like to have this. Especially as elm-make --docs=documentation.json seems to return a file containing just the two characters []...

vilterp commented 8 years ago

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 .

Deimos28 commented 8 years ago

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 .