Skip to content

Commit

Permalink
Switch to MkDocs for doc generation
Browse files Browse the repository at this point in the history
This allows us to use '.md' extensions in links (commercialhaskell#1506), and the
formatting is a bit nicer and closer to how GitHub renders.
WIP

WIP

WIP

WIP
  • Loading branch information
borsboom committed Feb 19, 2016
1 parent 1623e10 commit 1448a41
Show file tree
Hide file tree
Showing 38 changed files with 456 additions and 391 deletions.
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@ tags
/*.iml
/src/highlight.js
/src/style.css
/doc/_build
/_site/
12 changes: 6 additions & 6 deletions ChangeLog.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Release notes:
- Arch Linux: Stack has been adopted into the
[official community repository](https://www.archlinux.org/packages/community/x86_64/stack/),
so we will no longer be updating the AUR with new versions. See the
[install/upgrade guide](http://docs.haskellstack.org/en/stable/install_and_upgrade.html#arch-linux)
[install/upgrade guide](http://docs.haskellstack.org/en/stable/install_and_upgrade/#arch-linux)
for current download instructions.

Major changes:
Expand Down Expand Up @@ -142,16 +142,16 @@ Release notes:
source code, so please check the links on the website before submitting a PR
to fix them.
* The locations of the
[Ubuntu](http://docs.haskellstack.org/en/stable/install_and_upgrade.html#ubuntu)
[Ubuntu](http://docs.haskellstack.org/en/stable/install_and_upgrade/#ubuntu)
and
[Debian](http://docs.haskellstack.org/en/stable/install_and_upgrade.html#debian)
[Debian](http://docs.haskellstack.org/en/stable/install_and_upgrade/#debian)
package repositories have changed to have correct URL semantics according to
Debian's guidelines
[#1378](https://github.com/commercialhaskell/stack/issues/1378). The old
locations will continue to work for some months, but we suggest that you
adjust your `/etc/apt/sources.list.d/fpco.list` to the new location to avoid
future disruption.
* [openSUSE and SUSE Linux Enterprise](http://docs.haskellstack.org/en/stable/install_and_upgrade.html#opensuse-suse-linux-enterprise)
* [openSUSE and SUSE Linux Enterprise](http://docs.haskellstack.org/en/stable/install_and_upgrade/#opensuse-suse-linux-enterprise)
packages are now available, thanks to [@mimi1vx](https://github.com/mimi1vx).
Note: there will be some lag before these pick up new versions, as they are
based on Stackage LTS.
Expand Down Expand Up @@ -206,7 +206,7 @@ Major changes:

* GHCJS can now be used with stackage snapshots via the new `compiler` field.
* Windows installers are now available:
[download them here](http://docs.haskellstack.org/en/stable/install_and_upgrade.html#windows)
[download them here](http://docs.haskellstack.org/en/stable/install_and_upgrade/#windows)
[#613](https://github.com/commercialhaskell/stack/issues/613)
* Docker integration works with non-FPComplete generated images
[#531](https://github.com/commercialhaskell/stack/issues/531)
Expand Down Expand Up @@ -420,7 +420,7 @@ Major changes:
* Respect TemplateHaskell addDependentFile dependency changes ([#105](https://github.com/commercialhaskell/stack/issues/105))
* TH dependent files are taken into account when determining whether a package needs to be built.
* Overhauled target parsing, added `--test` and `--bench` options [#651](https://github.com/commercialhaskell/stack/issues/651)
* For details, see [Build commands documentation](http://docs.haskellstack.org/en/stable/build_command.html)
* For details, see [Build commands documentation](http://docs.haskellstack.org/en/stable/build_command/)

Other enhancements:

Expand Down
8 changes: 0 additions & 8 deletions GUIDE.md

This file was deleted.

19 changes: 19 additions & 0 deletions doc/CONTRIBUTING.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!DOCTYPE HTML>
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
This is more properly done using an HTTP redirect, but unfortunately
readthedocs.org's page redirection is broken (see
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
this file, and its reference in mkdocs.yml, can be removed. -->
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="1;url=CONTRIBUTING/">
<script type="text/javascript">
window.location.href = "CONTRIBUTING/" + window.location.hash
</script>
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically, follow the <a href="CONTRIBUTING/'>link to CONTRIBUTING/</a>.
</body>
</html>
19 changes: 19 additions & 0 deletions doc/ChangeLog.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!DOCTYPE HTML>
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
This is more properly done using an HTTP redirect, but unfortunately
readthedocs.org's page redirection is broken (see
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
this file, and its reference in mkdocs.yml, can be removed. -->
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="1;url=ChangeLog/">
<script type="text/javascript">
window.location.href = "ChangeLog/" + window.location.hash
</script>
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically, follow the <a href="ChangeLog/'>link to ChangeLog/</a>.
</body>
</html>
19 changes: 19 additions & 0 deletions doc/GUIDE.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!DOCTYPE HTML>
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
This is more properly done using an HTTP redirect, but unfortunately
readthedocs.org's page redirection is broken (see
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
this file, and its reference in mkdocs.yml, can be removed. -->
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="1;url=GUIDE/">
<script type="text/javascript">
window.location.href = "GUIDE/" + window.location.hash
</script>
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically, follow the <a href="GUIDE/'>link to GUIDE/</a>.
</body>
</html>
22 changes: 11 additions & 11 deletions doc/GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ all commands work cross-platform, unless explicitly stated otherwise.
## Downloading and Installation

The [documentation dedicated to downloading
stack](install_and_upgrade.html) has the most
stack](install_and_upgrade.md) has the most
up-to-date information for a variety of operating systems, including multiple
GNU/Linux flavors. Instead of repeating that content here, please go check out
that page and come back here when you can successfully run `stack --version`.
Expand Down Expand Up @@ -619,7 +619,7 @@ At the time of writing:
* Experimental custom snapshot support

The most up-to-date information can always be found in the
[stack.yaml documentation](yaml_configuration.html#resolver).
[stack.yaml documentation](yaml_configuration.md#resolver).

## Existing projects

Expand Down Expand Up @@ -725,7 +725,7 @@ Please choose one of the following commands to get started.
stack init --resolver lts-2.22
You'll then need to add some extra-deps. See the
[stack.yaml documentation](yaml_configuration.html#extra-deps).
[stack.yaml documentation](yaml_configuration.md#extra-deps).
You can also try falling back to a dependency solver with:
Expand Down Expand Up @@ -1028,7 +1028,7 @@ to build.

We're not going to cover the full generality of these arguments here; instead,
there's [documentation covering the full build command
syntax](build_command.html).
syntax](build_command.md).
Here, we'll just point out a few different types of arguments:

* You can specify a *package name*, e.g. `stack build vector`.
Expand Down Expand Up @@ -1165,7 +1165,7 @@ In addition to local directories, you can also refer to packages available in a
Git repository or in a tarball over HTTP/HTTPS. This can be useful for using a
modified version of a dependency that hasn't yet been released upstream. This is
a slightly more advanced usage that we won't go into detail with here, but it's
covered in the [stack.yaml documentation](yaml_configuration.html#packages).
covered in the [stack.yaml documentation](yaml_configuration.md#packages).

## Flags and GHC options

Expand Down Expand Up @@ -1253,7 +1253,7 @@ confusion.
Final point: if you have GHC options that you'll be regularly passing to your
packages, you can add them to your stack.yaml file (starting with
stack-0.1.4.0). See [the documentation section on
ghc-options](yaml_configuration.html#ghc-options)
ghc-options](yaml_configuration.md#ghc-options)
for more information.

## path
Expand Down Expand Up @@ -1546,7 +1546,7 @@ There are lots of resources available for learning more about stack:
* `--verbose` (or `-v`) — much more info about internal operations (useful for bug reports)
* The [home page](http://haskellstack.org)
* The [stack mailing list](https://groups.google.com/d/forum/haskell-stack)
* The [the FAQ](faq.html)
* The [the FAQ](faq.md)
* The [stack wiki](https://github.com/commercialhaskell/stack/wiki)
* The [haskell-stack tag on Stack Overflow](http://stackoverflow.com/questions/tagged/haskell-stack)
* [Another getting started with stack tutorial](http://seanhess.github.io/2015/08/04/practical-haskell-getting-started.html)
Expand Down Expand Up @@ -1603,13 +1603,13 @@ getting type information in Emacs. For more information, see
If you'd like to get some insight into the dependency tree of your packages, you
can use the `stack dot` command and Graphviz. More information is
[available in the Dependency visualization documentation](dependency_visualization.html).
[available in the Dependency visualization documentation](dependency_visualization.md).
### Travis with caching
Many people use Travis CI to test out a project for every Git push. We have [a
document devoted to
Travis](travis_ci.html). However, for
Travis](travis_ci.md). However, for
most people, the following example will be sufficient to get started:
```yaml
Expand Down Expand Up @@ -1689,7 +1689,7 @@ code inside a Docker image, which means:
a large initial download, but much faster builds

For more information, see
[the Docker-integration documentation](docker_integration.html).
[the Docker-integration documentation](docker_integration.md).

stack can also generate Docker images for you containing your built executables.
This feature is great for automating deployments from CI. This feature is not
Expand Down Expand Up @@ -1749,7 +1749,7 @@ in the common case or even to learn how to use the Nix tools (they're
called under the hood).

For more information, see
[the Nix-integration documentation](nix_integration.html).
[the Nix-integration documentation](nix_integration.md).

## Power user commands

Expand Down
19 changes: 19 additions & 0 deletions doc/MAINTAINER_GUIDE.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!DOCTYPE HTML>
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
This is more properly done using an HTTP redirect, but unfortunately
readthedocs.org's page redirection is broken (see
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
this file, and its reference in mkdocs.yml, can be removed. -->
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="1;url=MAINTAINER_GUIDE/">
<script type="text/javascript">
window.location.href = "MAINTAINER_GUIDE/" + window.location.hash
</script>
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically, follow the <a href="MAINTAINER_GUIDE/'>link to MAINTAINER_GUIDE/</a>.
</body>
</html>
3 changes: 1 addition & 2 deletions doc/MAINTAINER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,7 @@ to go:
"obvious" version in sequence (if doing a non-obvious jump) and replace
with new version
* Look for any links to "latest" documentation, replace with version tag
* Ensure all inter-doc links use `.html` extension (not `.md`)
* Ensure all documentation pages listed in `doc/index.rst`
* Ensure all documentation pages listed in `mkdocs.yaml`
* Check that any new Linux distribution versions added to
`etc/scripts/release.hs` and `etc/scripts/vagrant-releases.sh`
* Check that no new entries need to be added to
Expand Down
19 changes: 19 additions & 0 deletions doc/README.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!DOCTYPE HTML>
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
This is more properly done using an HTTP redirect, but unfortunately
readthedocs.org's page redirection is broken (see
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
this file, and its reference in mkdocs.yml, can be removed. -->
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="1;url=README/">
<script type="text/javascript">
window.location.href = "README/" + window.location.hash
</script>
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically, follow the <a href="README/'>link to README/</a>.
</body>
</html>
30 changes: 15 additions & 15 deletions doc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,18 @@ It features:

Downloads are available by operating system:

* [Windows](install_and_upgrade.html#windows)
* [Mac OS X](install_and_upgrade.html#mac-os-x)
* [Ubuntu](install_and_upgrade.html#ubuntu)
* [Debian](install_and_upgrade.html#debian)
* [CentOS / Red Hat / Amazon Linux](install_and_upgrade.html#centos-red-hat-amazon-linux)
* [Fedora](install_and_upgrade.html#fedora)
* [openSUSE / SUSE Linux Enterprise](install_and_upgrade.html#opensuse-suse-linux-enterprise)
* [Arch Linux](install_and_upgrade.html#arch-linux)
* [NixOS](install_and_upgrade.html#nixos)
* [Linux (general)](install_and_upgrade.html#linux)

[Upgrade instructions](install_and_upgrade.html#upgrade)
* [Windows](install_and_upgrade.md#windows)
* [Mac OS X](install_and_upgrade.md#mac-os-x)
* [Ubuntu](install_and_upgrade.md#ubuntu)
* [Debian](install_and_upgrade.md#debian)
* [CentOS / Red Hat / Amazon Linux](install_and_upgrade.md#centos-red-hat-amazon-linux)
* [Fedora](install_and_upgrade.md#fedora)
* [openSUSE / SUSE Linux Enterprise](install_and_upgrade.md#opensuse-suse-linux-enterprise)
* [Arch Linux](install_and_upgrade.md#arch-linux)
* [NixOS](install_and_upgrade.md#nixos)
* [Linux (general)](install_and_upgrade.md#linux)

[Upgrade instructions](install_and_upgrade.md#upgrade)

Note: if you are using cabal-install to install stack, you may need to pass a
constraint to work around a
Expand Down Expand Up @@ -106,7 +106,7 @@ executables.
Just try to add a new version in the `stack.yaml` file in the `extra-deps` section.

It was a really fast introduction on how to start to code in Haskell using `stack`.
If you want to go further, we highly recommend you to read the [`stack` guide](GUIDE.html).
If you want to go further, we highly recommend you to read the [`stack` guide](GUIDE.md).

#### How to contribute

Expand Down Expand Up @@ -135,13 +135,13 @@ stack build
#### Complete guide to stack

This repository also contains a complete [user guide to using stack
](GUIDE.html), covering all of the most common use cases.
](GUIDE.md), covering all of the most common use cases.


#### Questions, Feedback, Discussion

* For frequently asked questions about detailed or specific use-cases, please
see [the FAQ](faq.html).
see [the FAQ](faq.md).
* For general questions, comments, feedback and support please write
to [the stack mailing list](https://groups.google.com/d/forum/haskell-stack).
* For bugs, issues, or requests please
Expand Down
19 changes: 19 additions & 0 deletions doc/SIGNING_KEY.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!DOCTYPE HTML>
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
This is more properly done using an HTTP redirect, but unfortunately
readthedocs.org's page redirection is broken (see
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
this file, and its reference in mkdocs.yml, can be removed. -->
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="1;url=SIGNING_KEY/">
<script type="text/javascript">
window.location.href = "SIGNING_KEY/" + window.location.hash
</script>
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically, follow the <a href="SIGNING_KEY/'>link to SIGNING_KEY/</a>.
</body>
</html>
19 changes: 19 additions & 0 deletions doc/architecture.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!DOCTYPE HTML>
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
This is more properly done using an HTTP redirect, but unfortunately
readthedocs.org's page redirection is broken (see
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
this file, and its reference in mkdocs.yml, can be removed. -->
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="1;url=architecture/">
<script type="text/javascript">
window.location.href = "architecture/" + window.location.hash
</script>
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically, follow the <a href="architecture/'>link to architecture/</a>.
</body>
</html>
19 changes: 19 additions & 0 deletions doc/build_command.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<!DOCTYPE HTML>
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
This is more properly done using an HTTP redirect, but unfortunately
readthedocs.org's page redirection is broken (see
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
this file, and its reference in mkdocs.yml, can be removed. -->
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="1;url=build_command/">
<script type="text/javascript">
window.location.href = "build_command/" + window.location.hash
</script>
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically, follow the <a href="build_command/'>link to build_command/</a>.
</body>
</html>
Loading

0 comments on commit 1448a41

Please sign in to comment.