Skip to content

Commit 1448a41

Browse files
borsboomborsboom
committed
Switch to MkDocs for doc generation
This allows us to use '.md' extensions in links (#1506), and the formatting is a bit nicer and closer to how GitHub renders. WIP WIP WIP WIP
1 parent 1623e10 commit 1448a41

38 files changed

+456
-391
lines changed

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,4 @@ tags
1919
/*.iml
2020
/src/highlight.js
2121
/src/style.css
22-
/doc/_build
22+
/_site/

‎ChangeLog.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Release notes:
77
- Arch Linux: Stack has been adopted into the
88
[official community repository](https://www.archlinux.org/packages/community/x86_64/stack/),
99
so we will no longer be updating the AUR with new versions. See the
10-
[install/upgrade guide](http://docs.haskellstack.org/en/stable/install_and_upgrade.html#arch-linux)
10+
[install/upgrade guide](http://docs.haskellstack.org/en/stable/install_and_upgrade/#arch-linux)
1111
for current download instructions.
1212

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

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

425425
Other enhancements:
426426

‎GUIDE.md‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎doc/CONTRIBUTING.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!DOCTYPE HTML>
2+
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
3+
This is more properly done using an HTTP redirect, but unfortunately
4+
readthedocs.org's page redirection is broken (see
5+
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
6+
this file, and its reference in mkdocs.yml, can be removed. -->
7+
<html lang="en-US">
8+
<head>
9+
<meta charset="UTF-8">
10+
<meta http-equiv="refresh" content="1;url=CONTRIBUTING/">
11+
<script type="text/javascript">
12+
window.location.href = "CONTRIBUTING/" + window.location.hash
13+
</script>
14+
<title>Page Redirection</title>
15+
</head>
16+
<body>
17+
If you are not redirected automatically, follow the <a href="CONTRIBUTING/'>link to CONTRIBUTING/</a>.
18+
</body>
19+
</html>

‎doc/ChangeLog.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!DOCTYPE HTML>
2+
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
3+
This is more properly done using an HTTP redirect, but unfortunately
4+
readthedocs.org's page redirection is broken (see
5+
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
6+
this file, and its reference in mkdocs.yml, can be removed. -->
7+
<html lang="en-US">
8+
<head>
9+
<meta charset="UTF-8">
10+
<meta http-equiv="refresh" content="1;url=ChangeLog/">
11+
<script type="text/javascript">
12+
window.location.href = "ChangeLog/" + window.location.hash
13+
</script>
14+
<title>Page Redirection</title>
15+
</head>
16+
<body>
17+
If you are not redirected automatically, follow the <a href="ChangeLog/'>link to ChangeLog/</a>.
18+
</body>
19+
</html>

‎doc/GUIDE.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!DOCTYPE HTML>
2+
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
3+
This is more properly done using an HTTP redirect, but unfortunately
4+
readthedocs.org's page redirection is broken (see
5+
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
6+
this file, and its reference in mkdocs.yml, can be removed. -->
7+
<html lang="en-US">
8+
<head>
9+
<meta charset="UTF-8">
10+
<meta http-equiv="refresh" content="1;url=GUIDE/">
11+
<script type="text/javascript">
12+
window.location.href = "GUIDE/" + window.location.hash
13+
</script>
14+
<title>Page Redirection</title>
15+
</head>
16+
<body>
17+
If you are not redirected automatically, follow the <a href="GUIDE/'>link to GUIDE/</a>.
18+
</body>
19+
</html>

‎doc/GUIDE.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ all commands work cross-platform, unless explicitly stated otherwise.
4848
## Downloading and Installation
4949

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

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

624624
## Existing projects
625625

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

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

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

11701170
## Flags and GHC options
11711171

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

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

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

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

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

17541754
## Power user commands
17551755

‎doc/MAINTAINER_GUIDE.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!DOCTYPE HTML>
2+
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
3+
This is more properly done using an HTTP redirect, but unfortunately
4+
readthedocs.org's page redirection is broken (see
5+
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
6+
this file, and its reference in mkdocs.yml, can be removed. -->
7+
<html lang="en-US">
8+
<head>
9+
<meta charset="UTF-8">
10+
<meta http-equiv="refresh" content="1;url=MAINTAINER_GUIDE/">
11+
<script type="text/javascript">
12+
window.location.href = "MAINTAINER_GUIDE/" + window.location.hash
13+
</script>
14+
<title>Page Redirection</title>
15+
</head>
16+
<body>
17+
If you are not redirected automatically, follow the <a href="MAINTAINER_GUIDE/'>link to MAINTAINER_GUIDE/</a>.
18+
</body>
19+
</html>

‎doc/MAINTAINER_GUIDE.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,7 @@ to go:
3737
"obvious" version in sequence (if doing a non-obvious jump) and replace
3838
with new version
3939
* Look for any links to "latest" documentation, replace with version tag
40-
* Ensure all inter-doc links use `.html` extension (not `.md`)
41-
* Ensure all documentation pages listed in `doc/index.rst`
40+
* Ensure all documentation pages listed in `mkdocs.yaml`
4241
* Check that any new Linux distribution versions added to
4342
`etc/scripts/release.hs` and `etc/scripts/vagrant-releases.sh`
4443
* Check that no new entries need to be added to

‎doc/README.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!DOCTYPE HTML>
2+
<!-- This file exists only to redirect from old Sphinx URLs to new MkDocs URLs.
3+
This is more properly done using an HTTP redirect, but unfortunately
4+
readthedocs.org's page redirection is broken (see
5+
https://github.com/rtfd/readthedocs.org/issues/1826). Once that bug is fixed,
6+
this file, and its reference in mkdocs.yml, can be removed. -->
7+
<html lang="en-US">
8+
<head>
9+
<meta charset="UTF-8">
10+
<meta http-equiv="refresh" content="1;url=README/">
11+
<script type="text/javascript">
12+
window.location.href = "README/" + window.location.hash
13+
</script>
14+
<title>Page Redirection</title>
15+
</head>
16+
<body>
17+
If you are not redirected automatically, follow the <a href="README/'>link to README/</a>.
18+
</body>
19+
</html>

0 commit comments

Comments
 (0)