Merge pull request #243 from haskell/refactor-read-docs-website

Deduplicate docs, prepare to get rid of website

CONTRIBUTING.rst

@@ -0,0 +1 @@
+doc/contributing.rst

ChangeLog.md

@@ -238,6 +238,9 @@ The main focus of this release was revamping the build system and bootstrapping.
 * Happy is about 5 times faster on large examples, due to some
   changes in the LALR(1) algorithms.
 
+As of version 1.5, Happy is capable of parsing full Haskell.
+We have a Haskell parser that uses Happy, which will shortly be part of the library collection distributed with GHC.
+
 ## 1.2
 
 * Supports Haskell 1.4

README.md

@@ -4,62 +4,18 @@
 
 Happy is a parser generator for Haskell 98 (and later).
 
-* https://www.haskell.org/happy/
-* http://hackage.haskell.org/package/happy
-
-## Build Instructions
-
-Happy is normal Cabal-packaged Haskell executable, except for the fact that a
-pre-built Happy is *required* to build the full version of Happy, which is the
-default.
-
-- If you *do* have an existing Happy executable on the PATH or in the default
-  installation location (`~/.cabal/bin` for example), do regular
-  ```
-  $ cabal build
-  ```
-  like with any other project.
-
-- If you do *not* have an existing Happy executable, instead do
-  ```
-  $ cabal build -f -bootstrap
-  ```
-
-- If you install that minimial, non-bootstrapped happy
-  ```
-  $ cabal install -f -bootstrap
-  ```
-  you can then build normally (with the bootstrap flag enabled).
-
-*We're sorry the bootstrap process is a bit tedious right now; we hope to
-improve it in the future. The ideal fix would be to make cabal-installer's
-cycle detector to be less pessimistic, per
-https://github.com/haskell/cabal/issues/7189, so that the build tool dependency
-can be properly expressed and everything works automatically.*
-
-## Documentation & Examples
-
-Complete documentation can be found in the directory `/doc`, in reStructured Text format as is common for many Haskell tools' dococumentation.
-To build the documentation, use [Sphinx](https://www.sphinx-doc.org/).
-Alternatively, pre-formatted documentation is available from https://haskell-happy.readthedocs.io.
-
-The directory `/examples` contains some example parsers that use Happy.
-
-For information on copying and distributing this program, see the file
-LICENSE in this directory.
-
-## Contributing & Reporting Issues
-
-Bugs should be reported at: https://github.com/simonmar/happy/issues
-
 Happy Parsing!
 
-Simon.
+## Documentation
 
-## Current Maintainers
+Documentation is hosted on [Read the Docs](https://haskell-happy.readthedocs.io):
 
-- Vladislav Zavialov (@int-index)
+- [Online (HTML)](https://haskell-happy.readthedocs.io)
+- [PDF](https://haskell-happy.readthedocs.io/_/downloads/en/latest/pdf/)
+- [Downloadable HTML](https://haskell-happy.readthedocs.io/_/downloads/en/latest/htmlzip/)
 
-- John Ericson (@Ericson2314)
+For basic information of the sort typically found in a read-me, see the following sections of the docs:
 
-- Simon Marlow (@simonmar)
+- [Introduction](https://haskell-happy.readthedocs.io/en/latest/introduction.html)
+- [Obtaining Happy](https://haskell-happy.readthedocs.io/en/latest/obtaining.html)
+- [Contributing](https://haskell-happy.readthedocs.io/en/latest/contributing.html)

doc/contributing.rst

@@ -0,0 +1,63 @@
+.. _contributing:
+
+Contributing to Happy
+=====================
+
+.. highlight:: bash
+
+Source Code Repository
+----------------------
+
+Happy is hosted on `GitHub <https://github.com/haskell/happy>`__.
+As previously discussed in `bug-reports`_, we use the built-in `GitHub issue tracker <https://github.com/haskell/happy/issues>`__ for Happy.
+We also use `GitHub pull requests <https://github.com/haskell/happy/pulls>`__ for managing changes;
+feel free to submit them!
+
+Repo Layout
+-----------
+
+- ``src``: The source code for the Happy executable itself
+
+- ``packages/*``: The various packages that make up Happy behind the scenes, and are available for reuse for other purposes.
+
+- ``doc``: The documentation
+
+  This is in reStructured Text format as is common for many Haskell tools' documentation.
+  To build the documentation, use [Sphinx](https://www.sphinx-doc.org/).
+
+- ``examples``: Various examples of using Happy
+
+Build Instructions
+------------------
+
+Happy is normal Cabal-packaged Haskell executable, except for the fact that a
+pre-built Happy is *required* to build the full version of Happy, which is the default.
+
+- If you *do* have an existing Happy executable on the PATH or in the default
+  installation location (`~/.cabal/bin` for example), do regular
+
+  ::
+
+    $ cabal build
+
+  like with any other project.
+
+- If you do *not* have an existing Happy executable, instead do
+
+  ::
+
+    $ cabal build -f -bootstrap
+
+- If you install that minimial, non-bootstrapped happy
+
+  ::
+
+    $ cabal install -f -bootstrap
+
+  you can then build normally (with the bootstrap flag enabled).
+
+*We're sorry the bootstrap process is a bit tedious right now; we hope to
+improve it in the future. The ideal fix would be to make cabal-installer's
+cycle detector to be less pessimistic, per
+`<https://github.com/haskell/cabal/issues/7189>`_, so that the build tool dependency
+can be properly expressed and everything works automatically.*

doc/index.rst

@@ -9,13 +9,15 @@ Welcome to Happy's documentation!
    :caption: Contents
 
    introduction
+   obtaining
    using
    glr
    attribute-grammars
    invoking
    syntax
    info-files
    tips
+   contributing
 
 
 

doc/introduction.rst

@@ -1,4 +1,3 @@
-
 .. _sec-introduction:
 
 Introduction
@@ -63,10 +62,15 @@ Compatibility
 
 Happy is written in Glasgow Haskell.
 This means that (for the time being), you need GHC to compile it.
-Any version of GHC >= 6.2 should work.
+Any version of GHC >= 7.0 should work.
 
 Remember: parsers produced using Happy should compile without difficulty under any Haskell 98 compiler or interpreter. [1]_
 
+.. [1]
+   With one exception:
+   if you have a production with a polymorphic type signature, then a compiler that supports local universal quantification is required.
+   See :ref:`Type Signatures <sec-type-signatures>`.
+
 .. _sec-reporting-bugs:
 
 Reporting Bugs
@@ -75,7 +79,8 @@ Reporting Bugs
 .. index::
    single: bugs; reporting
 
-Any bugs found in Happy should be reported to me: Simon Marlow [email protected] including all the relevant information:
+Any bugs found in Happy should be reported in the `Happy issue tracker <https://github.com/haskell/happy/issues>`__.
+Please include all the relevant information:
 the compiler used to compile Happy,
 the command-line options used,
 your grammar file or preferably a cut-down example showing the problem,
@@ -122,15 +127,41 @@ If this license doesn't work for you, please get in touch.
    OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-.. _sec-obtaining:
+Acknowledgements
+----------------
 
-Obtaining Happy
----------------
+Original authors
+~~~~~~~~~~~~~~~~
 
-Happy's web page can be found at http://www.haskell.org/happy/.
-Happy source and binaries can be downloaded from there.
+Happy versions up to 0.9 were written by Andy Gill and Simon Marlow.
 
-.. [1]
-   With one exception:
-   if you have a production with a polymorphic type signature, then a compiler that supports local universal quantification is required.
-   See :ref:`Type Signatures <sec-type-signatures>`.
+Improvements since 0.9 are by Simon Marlow (and various other contributors).
+
+Generalized LR Backend
+^^^^^^^^^^^^^^^^^^^^^^
+
+- Ben Medlock
+
+- Paul Callaghan
+
+Current Maintainers
+~~~~~~~~~~~~~~~~~~~
+
+- Andreas Abel (@andreasabel)
+
+- Vladislav Zavialov (@int-index)
+
+- John Ericson (@Ericson2314)
+
+- Simon Marlow (@simonmar)
+
+Other contributors
+~~~~~~~~~~~~~~~~~~
+
+The data is in the Git history.
+GitHub can render that in `various ways <https://github.com/simonmar/happy/graphs/contributors>`__.
+
+Extra
+~~~~~
+
+A big thanks to Ben Jones for loaning out his copy of the Roger Hargreaves *Mr Happy* book.

doc/obtaining.rst

@@ -0,0 +1,35 @@
+.. _sec-obtaining:
+
+Obtaining Happy
+===============
+
+.. highlight:: bash
+
+If you just want to *use* Happy, you can build from a release.
+This should work the same as any other Haskell package.
+
+Happy itself and its examples are intended to work with GHC >= 7.0.
+
+Haskell-specific way
+--------------------
+
+From `Hackage <https://hackage.haskell.org/package/happy>`__ via `Cabal Install <https://www.haskell.org/cabal/>`__::
+
+   $ cabal install happy
+
+From `Stackage <https://www.stackage.org/package/happy>`__ via `Stack <https://haskellstack.org>`__::
+
+   $ stack install happy
+
+Moreover, ``cabal`` will automatically install the required version of ``happy`` based on ``build-tools``/``build-tool-depends`` `declarations <http://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-build-tool-depends>`__.
+
+Operating System way
+--------------------
+
+Because Happy is a dependency of GHC, it is often packaged by operating systems.
+`Repology <https://repology.org>`__ aggregates this info across many distros and operating systems, and Happy is actually listed twice:
+
+- https://repology.org/project/haskell:happy/versions
+- https://repology.org/project/happy/versions
+
+The table contains links to the individual OS packages, which should provide installation instructions.