include hadrian build instructions in readme

Also moved readme out to root dir for better forge rendering.

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