Upgrade Html output to Semantic-UI

[athanclark]

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:

• Better typesetting for type signatures
• Responsively designed front-end
  • I like the look-and-feel for Semantic-UI's documentation (link below), for instance
• Relevant source-code per item: http://semantic-ui.com/collections/grid.html - click "view source" to the right - the angle brackets <> might be nice

Please let me know what you think or concerns you may have - I would really like to make the documentation system better!

[Fuuzetsu]

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]

Ah! That's great news. Maybe we could work on a JSON api for what
haddock-core should produce?

With all your other notes, I completely agree - the default theme should be
completely standalone and have minimalistic Html. That's why I wanted to
use this library - it's only job is to provide css classes for structuring
the Html visually, in a nice presentation. I think it might be worth a shot
to make a new default theme to Haddock. There is a javascript file to
bootstrap for it to work, but I'm sure I can work around it.

Also, as an example of the poor type setting for complicated type
signatures, take a look at this:
http://hackage.haskell.org/package/nested-routes-0.3.1/docs/Web-Routes-Nested.html#v:handleParse

• it's practically unreadable. It would be nice to adopt GHC's typesetting
  for large constraints here.

I also entirely agree that the documentation, visually, should grow to
become separate from Haddock. I'll start cooking something up :)

On Mon, May 4, 2015 at 4:05 PM, Mateusz Kowalczyk notifications@github.com
wrote:

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.

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, easy 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.

—
Reply to this email directly or view it on GitHub
#389 (comment).

[hvr]

IMO, for hosting docs on Hackage (if that's even the goal/target here), it would be very important to have something that can be generated offline and be served statically. This would be very limiting for a JSON-api based approach

[athanclark]

I agree, Herbert - I'm not trying to force some runtime, dynamic JSON api - I'm merely trying to sort out a Haskell Record, moreso, as an API for hackage docs - to be used as the seam between "themes" and the "core" - I just used JSON as a reference - by no means does it have to be (in fact... why did I say JSON?! 'doh!).

[Fuuzetsu]

There are issues even with exposing a sane Haskell API right now so JSON is a bit out of reach currently even if we wanted.