[GHC] #14144: Standardize binary distribution doc files
#14144: Standardize binary distribution doc files -------------------------------------+------------------------------------- Reporter: patrickdoc | Owner: (none) Type: feature | Status: new request | Priority: normal | Milestone: Component: Build System | Version: 8.2.1 Keywords: | Operating System: Unknown/Multiple Architecture: | Type of failure: None/Unknown Unknown/Multiple | Test Case: | Blocked By: Blocking: | Related Tickets: Differential Rev(s): | Wiki Page: -------------------------------------+------------------------------------- I'm making a pass at the documentation in general, and next up on my list is simplifying the building process a bit. I hope to create something like `docs/dist-install` that would collect and hold all of the generated documentation. This would help in writing the docs, as you could verify links, say, from the user's guide to the library documentation. This would also allow installation and distribution to mainly be a `cp`. While looking into this, I ran into some discrepancies between releases. The contents of !https://downloads.haskell.org/~ghc/VERSION/docs for [https://downloads.haskell.org/~ghc/7.10-latest/docs 7.10], [https://downloads.haskell.org/~ghc/8.0-latest/docs 8.0], and [https://downloads.haskell.org/~ghc/latest/docs 8.2] are all different. 8.0 dropped `*.ps` files and `haddock.pdf`. 8.2 now additionally holds a `windows` folder that has a wide array of binaries and documentation. Going back further, the `Cabal` user's guide used to be included. I searched around for a reason that it was dropped and only found a git commit citing the change from `docbook`. But now most sources use `Sphinx`, so we could generate and include them if we so wished. The `Cabal` guide can be found at: * https://www.haskell.org/cabal/users-guide/ (Version 1.24.2) * https://cabal.readthedocs.io/en/latest/ (Versions 2.0 and HEAD) The `Haddock` guide can be found at: * https://www.haskell.org/haddock/doc/html (Version 2.15.0) * https://haskell-haddock.readthedocs.io/en/latest/ (Versions 2.18.0 and HEAD) * https://downloads.haskell.org/~ghc/latest/docs/haddock.html.tar.xz (GHC release version) Unfortunately, the www.haskell.org links are the most prominent when Googled. To bring this back to a point, I would like to clean up the `docs` folder of the distribution. The `windows` folder inside seems like it might be a mistake. Additionally, `Cabal` and `Haddock` have ended up in strange positions, and I think they probably could both use the same solution. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14144 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14144: Standardize binary distribution doc files -------------------------------------+------------------------------------- Reporter: patrickdoc | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: Component: Build System | Version: 8.2.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by bgamari): Yes, the documentation preparation infrastructure is a disaster. Here are a few notes that may be of interest, * I use https://github.com/bgamari/ghc-utils/blob/master/rel- eng/upload.sh#L139 to prepare the documentation that is uploaded to `downloads.haskell.org`. * This script uses the `distrib/mkDocs/mkDocs` script in the GHC tree; this script requires both a Windows and Linux bindist tarball, from which it extracts Haddock and user guide documentation * The `windows` folder in the 8.2 downloads folder appears to be a stale artifact from a failed run of the above script; I have deleted it. * Ultimately we want to have binary distributions and documentation snapshots generated by our continuous integration infrastructure. Building something like `docs/dist-install` would make this much easier. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14144#comment:1 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14144: Standardize binary distribution doc files -------------------------------------+------------------------------------- Reporter: patrickdoc | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: Component: Build System | Version: 8.2.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by patrickdoc): Do we want to include the Haddock and Cabal guides in distributions? As it stands right now, the distribution only has the zipped html of the Haddock guide. We could also provide full html (which would be browsable like the GHC guide) and/or a pdf. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14144#comment:2 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14144: Standardize binary distribution doc files -------------------------------------+------------------------------------- Reporter: patrickdoc | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: Component: Build System | Version: 8.2.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by bgamari): That is a good question; it's not clear to me whether these should really be bundled with GHC. However, as we currently ship both I suspect we should include at least their HTML guides; these should be linked to from `docs/index.html.in`. Incidentally, it would be great if `docs/index.html.in` were revamped; it currently looks like it was written in 1991. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14144#comment:3 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14144: Standardize binary distribution doc files -------------------------------------+------------------------------------- Reporter: patrickdoc | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: Component: Build System | Version: 8.2.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by patrickdoc): I've worked through a number of these problems in Hadrian, and opened a PR for comments [https://github.com/snowleopard/hadrian/pull/413]. Some more comments specifically about this ticket: Cabal's guide's configuration requires the "Read the Docs" theme. Packaging the theme inside the folder or requiring the user to install it both seem wrong to me, so it might be nice to have a default theme for local building. But that would have to be changed in the `cabal/Cabal/doc/conf.py` source. Building all of the docs on a single platform should be doable. However, the current implementation needs `package-data.mk` generated by `ghc-cabal configure`. This fails to configure `Win32` on Unix, and I would imagine the opposite is also true. However, I believe the data should be attainable just from the cabal file. I'll need to do some research to see if we can get by without `ghc-cabal` for the docs. I have managed to eliminate the need for `gen_contents_index`, which just leaves the mkDocs script. This script really just unifies the documentation built on both platforms, so solving the above would remove the need for this script. Likewise your upload script should become much simpler. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14144#comment:4 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14144: Standardize binary distribution doc files -------------------------------------+------------------------------------- Reporter: patrickdoc | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: Component: Build System | Version: 8.2.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by patrickdoc): It appears that building all the docs on a single platform is not possible, unfortunately. Haddock cannot process `.hsc` files, but we cannot generate the associated `.hs` files because we do not have the headers. For example, `Win32/System/Types.hsc` includes `windows.h` and so cannot be preprocessed. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14144#comment:5 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#14144: Standardize binary distribution doc files -------------------------------------+------------------------------------- Reporter: patrickdoc | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: Component: Build System | Version: 8.2.1 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by bgamari): Ahh yes, that is unfortunate. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/14144#comment:6 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
participants (1)
-
GHC