Backpack documentation in the user manual.

[ezyang]

Stack from ghstack:

• Backpack documentation in the user manual. #7306 Backpack documentation in the user manual.

Fixes #4761

Signed-off-by: Edward Z. Yang [email protected]

[fgaz]

/cc @cartazio

[cartazio]

Yay! Is there a good way to look at a preview render?
thus is great!

[ezyang]

I don't know! It's been a while. It looks like making this a stack diff also broke CI, so I might need to reopen this PR differently.

[emilypi]

LGTM, thanks @ezyang. What's this stack diff you're talking about?

found errors building locally

[emilypi]

It looks like there's a bad hyperlink in here. Building locally, i get the following:

WARNING: You are using pip version 20.1.1; however, version 21.0.1 is available.
You should consider upgrading via the '/Users/emilypi/haskell/cabal/.python-sphinx-virtualenv/bin/python3.7 -m pip install --upgrade pip' command.
Running Sphinx v3.1.2
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 6 changed, 0 removed
reading sources... [100%] setup-commands                                                                                                                                                                   
/Users/emilypi/haskell/cabal/doc/cabal-package.rst:2139: WARNING: invalid pair index entry '; package.cabal field'
/Users/emilypi/haskell/cabal/doc/cabal-project.rst:2: WARNING: Duplicate ID: "cfg-field-type".
/Users/emilypi/haskell/cabal/doc/file-format-changelog.rst:161: WARNING: Unknown target name: "backpack".
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] setup-commands                                                                                                                                                                    
generating indices...  genindex cabal-projectindexdone
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 3 warnings.

The first warning is seen on master, but the rest are related to this PR. I sense a conflict. It would be nice to not add additional warnings if we can, but, since they are warnings, I can run through and fix it up after this PR. Your choice! I built the docs locally and everything renders appropriately:

[cartazio]

this alone is a great start! (thx for the render)

some questions: which parts of the linked ghc docs are "stable specs" of how things do or dont work across the matrix of ghc and cabal versions? (eg, whats the min version of cabal/ghc needed for various features we do have, and for various limitations/bugs to be avoided?)

[ezyang]

@emilypi I fixed them! Thanks for reminding me to run the local build.

@cartazio Fortunately, Backpack feature development has very much been "no more new features after I finished my PhD". So basically any version of GHC after Backpack was put in is good. There is a Cabal parser that was fixed later but it's already prominently called out in the documentation. Not sure if this is satisfying to you!

[emilypi]

@ezyang did you mean to close this?

[ezyang]

yeah, due to technical difficulties I can only land ghstack PRs by closing, not "merging"

[fgaz]

Can we delete the gh/ezyang/1 branches?

[ezyang]

yeah (and I recently fixed ghstack to automatically delete the branches)