Fuuzetsu
commented
9 years ago It's a very nice front-end for making responsive web applications & what have you - something like twitter bootstrap++.
Is Haddock HTML output what one would consider a ‘responsive web application’?
I'll see what I can do for tying this all together in a separate branch, to see if it would be a good "upgrade".
That would be very interesting to see.
Better typesetting for type signatures
Better how?
I like the look-and-feel for Semantic-UI's documentation (link below), for instance
To me it looks like a lot of wasted space. Library documentation is very, very rarely in an article form that is meant to be read in-order and/or in full so I question this style of documentation. The ‘where in the article you are’ thing at a side seems useless for our usecase. But again I would have to see some kind of concept first to decide.
Relevant source-code per item
Well, I see two things here. One is that we have a section which we can collapse and expand. We can do that already. Second is some kind of automatic source code insertion: does the site you linked do that? If it's just manually typed out then we're done. If it's automatic then we have issues opened about this already that you may wish to have a look at. It's non-trivial. (EDIT: By the way, I didn't even see the <> and had to look for it to realise what you were even referring to. Not great…)
Please let me know what you think or concerns you may have
My main concerns are, in general terms, as follows: compatibility with current development and deployment setup, compatibility with various user setups, ease of maintenance.
In more specific terms: Haddock needs to be able to generate HTML docs without many dependencies. It needs to work inside GHC tree (of the developer!) without major issues. This is unfortunately our main limitation regards dependencies.
The generated documentation needs to be viewable by all users, including those without JavaScript and those using text browsers or even their text editors to browse it. That is, any JS needs to be completely optional: it's there for convenience or easy of viewing at best. If some part of the basic functionality would now require JavaScript to work in reasonable way, I don't want to accept it.
Lastly, maintenance convenience. In other words, my convenience. I'm not a web developer: currently I can make minor changes to the Haskell code that generates the HTML and play with it until it works. If the new system requires me to write CSS/JS/whatever for the things I was able to write Haskell so far, I'm not enthusiastic about it. Even today, if there is something that requires changing existing CSS/JS, I try to find someone else to do that. It sucks but I'm one person only :). I also don't know how the existing Haskell code would talk to this semantic-ui setup in practice so I wonder if you could explain a bit.
I would really like to make the documentation system better!
I'm very glad! I have already outlined my concerns above. I think the changes you are planning or would like to see can be put on the ‘it'd be really great to have but for various reasons we can't do it in core ourselves’ pile. But I don't want to throw away nice things either. I want to encourage a system where Haddock itself is a fairly small core: it talks to GHC, munges some data into more usable form, parses comments. Then other people can write all those nice things which use this as a backend. If your changes are extensive, I think we should focus on making it easy for you and others to implement such changes as a separate package. I think people are much more likely to write extensions and plugins if they can use whatever they want and don't have to be boxed into GHC-only dependencies and bottlenecked by what I can maintain.
In conclusion, please do go ahead and try to implement or demonstrate your idea but be aware that we will most likely not be able to put it in this package but I would be more than happy to help to make it possible for it to live in a separate package and make it easy for others to use. If it's easy to deploy and people like it, there is no reason why we couldn't make such an external package a default on Hackage or whatever in a distant future.
athanclark
hvr
It's a very nice front-end for making responsive web applications & what have you - something like twitter bootstrap++. I'll see what I can do for tying this all together in a separate branch, to see if it would be a good "upgrade".
There are a lot of features that could also go into this upgrade:
<>might be nicePlease let me know what you think or concerns you may have - I would really like to make the documentation system better!