diff options
| -rw-r--r-- | README.org (renamed from haddock-api/README.org) | 81 |
1 files changed, 69 insertions, 12 deletions
diff --git a/haddock-api/README.org b/README.org index 3bd64d32..fb6d7e19 100644 --- a/haddock-api/README.org +++ b/README.org @@ -14,16 +14,15 @@ invoke haddock to generate org files, of the Org Mode. ** Examples +- [[https://ypei.org/assets/haddorg-output/hierarchy-e2f0094c.org.gz][Haskell Hierarchy Libraries]], built at [[https://gitlab.haskell.org/ghc/ghc/-/commit/e2f0094c315746ff15b8d9650cf318f81d8416d7][ghc commit e2f0094c]]. - [[https://ypei.org/assets/haddorg-output/base-4.16.1.0.org.gz][base-4.16.1.0.org]] +- [[https://ypei.org/assets/haddorg-output/ghc-9.5-e2f0094c.org.gz][ghc-9.5-e2f0094c.org]], GHC API docs built at [[https://gitlab.haskell.org/ghc/ghc/-/commit/e2f0094c315746ff15b8d9650cf318f81d8416d7][ghc commit e2f0094c]]. - [[https://ypei.org/assets/haddorg-output/ghc-lib-parser-9.2.2.20220307.org.gz][ghc-lib-parser-9.2.2.20220307.org]], which can be used as a fake ghc - for cross-package linking -- lens -- [[https://ypei.org/assets/haddorg-output/haddorg-api-2.26.1.org.gz][haddorg-api-2.26.1.org]], also in this repository -- [[https://ypei.org/assets/haddorg-output/haddock-library-2.26.1.org.gz][haddock-library-2.26.1.org]] -- [[https://ypei.org/assets/haddorg-output/haddorg-ghc-base.org.gz][haddorg-api + haddock-library + fake ghc + base]], demonstrating - cross-package linking -- [[https://ypei.org/assets/haddorg-output/fsd-sqlite-simple-debian.org.gz][fsd + sqlite-simple + debian]], to demonstrating cross-package linking -- and [[https://ypei.org/assets/haddorg-output/][more...]] + for cross-package linking. +- [[https://ypei.org/assets/haddorg-output/haddorg-api-2.26.1.org.gz][haddorg-api-2.26.1.org]] +- [[https://ypei.org/assets/haddorg-output/lens-5.1.org.gz][lens-5.1.org]] +- [[https://ypei.org/assets/haddorg-output/fsd-sqlite-simple-debian.org.gz][fsd + sqlite-simple + debian]], demonstrating cross-package linking +- and [[https://ypei.org/assets/haddorg-output/][more...]], including [[https://ypei.org/assets/haddorg-output/hierarchy-e2f0094c/][all ghc libraries]] built at [[https://gitlab.haskell.org/ghc/ghc/-/commit/e2f0094c315746ff15b8d9650cf318f81d8416d7][ghc commit e2f0094c]]. ** Install @@ -67,19 +66,77 @@ exeprog="haddock" #+begin_src sh haddock Hello.hs --org +ls *.org # If success, the org file should be placed here #+end_src *** With cabal -After telling cabal to use haddock built with haddorg-api (see -[[Install]]), cd into the package you want to build the org documentation -for, and run: + +Follow instructions in [[Install]] to tell cabal to use haddock built with +haddorg-api. Using lens-5.1 as an example package, to fetch a package +from Hackage, one may use ~cabal unpack~: + +#+begin_src sh +cabal unpack lens-5.1 +#+end_src + +Now cd into the package you want to build the org documentation for, +and run the commands: #+begin_src sh +cd lens-5.1 cabal haddock --haddock-option=--org +ls lens-5.1.org # If success, the org file should be placed here #+end_src If success, a fresh new org documentation will be placed under the -package directory. +package directory (not in dist-newstyle!). + +*** With Hadrian + +In order to build documentation for GHC API or Haskell Hierarchical +Libraries, one may need to use the GHC build tool hadrian to invoke +Haddock. + +It is tricky as the ghc repo tracks [[https://gitlab.haskell.org/ghc/haddock/][its own haddock]] as a submodule, +which is built by hadrian and invoked for the documentation. Compared +to [[https://github.com/haskell/haddock][the official haddock repo]] this haddock can be ahead in some commits +as it has to build against the bleeding-edge GHC libraries (ghc api, +base, ghc-prim, ...) in ghc repo, and behind in some commits as the +official repo make changes to improve haddock itself. + +The haddorg-api repo at <https://g.ypei.me/haddock.git> does have a +[[https://g.ypei.me/haddock.git/?h=ghc-gitlab-ghc-head][ghc-gitlab-ghc-head branch]] to track the ghc-head branch of ghc haddock +repo. In fact, it was used to build ghc and haskell hierarchical +libraries org documentation so it is not impossible. But this branch +can go out of sync with the official ghc repo, and even if it stays in +sync all the time, one still needs to manually find out which commit +on the ghc haddock repo ghc-head branch corresponds to which commit on +the ghc-gitlab-ghc-head branch. + +The following is instructions on how to run haddock with hadrian, +where the reader may need to figure out the merge part, if a suitable +commit on the [[https://g.ypei.me/haddock.git/?h=ghc-gitlab-ghc-head][ghc-gitlab-ghc-head branch]] cannot be found. + +First, clone ghc with all its submodules. For example, to perform a +shallow clone, do: + +#+begin_src sh +git clone --depth 1 --recurse-submodules https://gitlab.haskell.org/ghc/ghc.git +#+end_src + +Then, update the flags in the hadrian code, merge the org backend +related commits into the haddock submodule located at ~utils/haddock~, +and build the documentation as usual: + +#+begin_src sh +cd ghc +# Edit ./hadrian/src/Settings/Builders/Haddock.hs by adding an --org flag. +# Merge org backend commits into ./utils/haddock, resolve any conflicts that +# may arise +./boot && ./configure +hadrian/build docs -j --flavour=Quick +ls *.org # If success, the org files should be placed here +#+end_src ** Tips |