Ben Gamari authored 6 years ago and Ben Gamari committed 6 years ago

The Mathjax CDN no longer exists. Use CDNJS instead.

See #15006.

Test Plan: Build HTML users guide, see whether math is rendered.

Reviewers: alpmestan

Reviewed By: alpmestan

Subscribers: thomie, carter

GHC Trac Issues: #15006

Differential Revision: https://phabricator.haskell.org/D4603

(cherry picked from commit 803178a5)

Ben Gamari authored 7 years ago and Ben Gamari committed 7 years ago

Previously the included package lists took a disproportionate amount of
space in the resulting document and were difficult to maintain. Turn it
into a table.

Subscribers: rwbarton, thomie

Differential Revision: https://phabricator.haskell.org/D4230

patrickdoc authored 7 years ago and Ben Gamari committed 7 years ago

This removes all dependencies the users guide had on `mkUserGuidePart`.
The generation of the flag reference table and the various pieces of the
man page is now entirely contained within the Spinx extension
`flags.py`. You can see the man page generation on the orphan page
https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ghc.html

The extension works by collecting all of the meta-data attached to the
`ghc-flag` directives and then formatting and displaying it at
`flag-print` directives. There is a single printing directive that can
be customized with two options, what format to display (table, list, or
block of flags) and an optional category to limit the output to
(verbosity, warnings, codegen, etc.).

New display formats can be added by creating a function
`generate_flag_xxx` (where `xxx` is a description of the format) which
takes a list of flags and a category and returns a new `xxx`. Then just
add a reference in the dispatch table `handlers`. That display can now
be run by passing `:type: xxx` to the `flag-print` directive.

`flags.py` contains two maps of settings that can be adjusted. The first
is a canonical list of flag categories, and the second sets default
categories for files.

The only functionality that Sphinx could not replace was the
`what_glasgow_exts_does.gen.rst` file. `mkUserGuidePart` actually just
reads the list of flags from `compiler/main/DynFlags.hs` which Sphinx
cannot do. As the flag is deprecated, I added the list as a static file
which can be updated manually.

Additionally, this patch updates every single documented flag with the
data from `mkUserGuidePart` to generate the reference table.

Fixes #11654 and, incidentally, #12155.

Reviewers: austin, bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #11654, #12155

Differential Revision: https://phabricator.haskell.org/D3839

Ben Gamari authored 7 years ago and Ben Gamari committed 7 years ago

Previously you had to painstakingly construct the URI to the haddock
documentation. Now the Python bits have enough smarts to construct this
themselves.

Reviewers: austin, patrickdoc

Reviewed By: patrickdoc

Subscribers: rwbarton, thomie

Differential Revision: https://phabricator.haskell.org/D3785

Fixes #14020, #14016, #14015, #14019

patrickdoc authored 7 years ago and Ben Gamari committed 7 years ago

This patch does three things:

1.) It simplifies the flag parsing code in `conf.py` to properly display
flag definitions created by `.. (ghc|rts)-flag::`. Additionally, all flag
references must include the associated arguments. Documentation has been
added to `editing-guide.rst` to explain this.

2.) It normalizes all flag definitions to a similar format. Notably, all
instances of `<>` have been replaced with `⟨⟩`. All references across the
users guide have been updated to match.

3.) It fixes a couple issues with the flag reference table's generation code,
which did not handle comma separated flags in the same cell and did not
properly reference flags with arguments.

Test Plan:
`SPHINXOPTS = -n` to activate "nitpicky" mode, which reports all broken
references. All remaining errors are references to flags without any
documentation.

Reviewers: austin, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #13980

Differential Revision: https://phabricator.haskell.org/D3778

niteria authored 7 years ago and Ben Gamari committed 7 years ago

If you go to
https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/index.html
the window title has `<release>` in it.  I don't understand how it all
works, but inspired by the line below which produces a correct string in
the docs I just blindly changed it in the same way.  Cabal appears to
have the same problem.

Test Plan:
it'd be nice if I could check the result
on harbormaster, can I?

Reviewers: thomie, bgamari, austin

Reviewed By: bgamari

Subscribers: rwbarton, simonmar

Differential Revision: https://phabricator.haskell.org/D3458

Ben Gamari authored 8 years ago and Ben Gamari committed 8 years ago

Reviewers: austin, hsyl20

Reviewed By: hsyl20

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D2921

harendra authored 8 years ago and Ben Gamari committed 8 years ago

Reviewers: austin, bgamari, ezyang

Reviewed By: ezyang

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D2464

This was introduced by a cut-and-paste error.

The madness that is latex never ceases to amaze.

Summary:
commit a034031a did not
fix problem completely. Stack overflows still occasionally
happen.

Easy to test by the following Torture Test:

  while sphinx-build -T -N -E -a -b html \
        -d docs/users_guide/.doctrees-html \
        -D latex_paper_size=letter \
        docs/users_guide docs/users_guide/build-html/users_guide
  do
    echo again
  done

sphinx build large nested data structures when parses GHC manual
(docs/users_guide/glasgow_exts.rst is 455KB in size) which
can't be serialized useing default python call stack depth of 1000
calls.

The patch increases stack depth 10 times. Survived 2 hours of
Torture Test.

Signed-off-by: Sergei Trofimovich <siarheit@google.com>

Test Plan: ran Torture Test to make sure it is stable

Reviewers: austin, bgamari

Reviewed By: bgamari

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D1809

GHC Trac Issues: #10950

And GHCi commands. This makes cross-referencing much easier.

Also normalize markup a bit and add some missing flags.

Ben Gamari authored 9 years ago and Ben Gamari committed 9 years ago

Note only does this make the markup cleaner and more semantic, but it
clears up some warnings and enables proper hyperlinks. Yay Sphinx!

While I was at it I generally cleaned up the markup

Test Plan: Read it

Reviewers: hvr, thomie, austin

Differential Revision: https://phabricator.haskell.org/D1730

inputenv /= inputenc