From 1448a41263b8f4a7e972b8f65b264926476f86e1 Mon Sep 17 00:00:00 2001 From: Emanuel Borsboom Date: Fri, 19 Feb 2016 04:16:03 -0800 Subject: [PATCH] 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 --- .gitignore | 2 +- ChangeLog.md | 12 +- GUIDE.md | 8 - doc/CONTRIBUTING.html | 19 ++ doc/ChangeLog.html | 19 ++ doc/GUIDE.html | 19 ++ doc/GUIDE.md | 22 +-- doc/MAINTAINER_GUIDE.html | 19 ++ doc/MAINTAINER_GUIDE.md | 3 +- doc/README.html | 19 ++ doc/README.md | 30 ++-- doc/SIGNING_KEY.html | 19 ++ doc/architecture.html | 19 ++ doc/build_command.html | 19 ++ doc/conf.py | 288 ------------------------------ doc/dependency_visualization.html | 19 ++ doc/docker_integration.html | 19 ++ doc/faq.html | 19 ++ doc/faq.md | 12 +- doc/ghcjs.html | 19 ++ doc/ghcjs.md | 2 +- doc/index.html | 1 + doc/index.rst | 38 ---- doc/install_and_upgrade.html | 19 ++ doc/install_and_upgrade.md | 6 +- doc/nix_integration.html | 19 ++ doc/nonstandard_project_init.html | 19 ++ doc/nonstandard_project_init.md | 2 +- doc/shell_autocompletion.html | 19 ++ doc/travis_ci.html | 19 ++ doc/travis_ci.md | 4 +- doc/yaml_configuration.html | 19 ++ doc/yaml_configuration.md | 4 +- mkdocs.yml | 57 ++++++ src/Stack/Config.hs | 6 +- src/Stack/Init.hs | 4 +- src/Stack/Setup.hs | 2 +- src/Stack/Types/Config.hs | 2 +- 38 files changed, 456 insertions(+), 391 deletions(-) delete mode 100644 GUIDE.md create mode 100644 doc/CONTRIBUTING.html create mode 100644 doc/ChangeLog.html create mode 100644 doc/GUIDE.html create mode 100644 doc/MAINTAINER_GUIDE.html create mode 100644 doc/README.html create mode 100644 doc/SIGNING_KEY.html create mode 100644 doc/architecture.html create mode 100644 doc/build_command.html delete mode 100644 doc/conf.py create mode 100644 doc/dependency_visualization.html create mode 100644 doc/docker_integration.html create mode 100644 doc/faq.html create mode 100644 doc/ghcjs.html create mode 120000 doc/index.html delete mode 100644 doc/index.rst create mode 100644 doc/install_and_upgrade.html create mode 100644 doc/nix_integration.html create mode 100644 doc/nonstandard_project_init.html create mode 100644 doc/shell_autocompletion.html create mode 100644 doc/travis_ci.html create mode 100644 doc/yaml_configuration.html create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index f3cafdcf39..6bcdedc053 100644 --- a/.gitignore +++ b/.gitignore @@ -19,4 +19,4 @@ tags /*.iml /src/highlight.js /src/style.css -/doc/_build +/_site/ diff --git a/ChangeLog.md b/ChangeLog.md index 75fe721bf9..38f9151168 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -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: @@ -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. @@ -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) @@ -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: diff --git a/GUIDE.md b/GUIDE.md deleted file mode 100644 index 819f58b94d..0000000000 --- a/GUIDE.md +++ /dev/null @@ -1,8 +0,0 @@ -##### Please Note: -The __GUIDE__ document has [moved to a new location](http://docs.haskellstack.org/en/stable/GUIDE.html). -The file you're viewing now remains as a pointer to the new file for a limited time. -Please update your personal links as needed. - - -*Maintainer note:* -*This file location was deprecated 2015 September; its planned removal date is 2016 January.* diff --git a/doc/CONTRIBUTING.html b/doc/CONTRIBUTING.html new file mode 100644 index 0000000000..0e9ecd428a --- /dev/null +++ b/doc/CONTRIBUTING.html @@ -0,0 +1,19 @@ + + + + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'stackdoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', - -# Latex figure (float) alignment -#'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'stack.tex', u'stack Documentation', - u'Stack contributors', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'stack', u'stack Documentation', - [author], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'stack', u'stack Documentation', - author, 'stack', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - -source_parsers = { - '.md': CommonMarkParser, -} diff --git a/doc/dependency_visualization.html b/doc/dependency_visualization.html new file mode 100644 index 0000000000..bb2e61ab07 --- /dev/null +++ b/doc/dependency_visualization.html @@ -0,0 +1,19 @@ + + + + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the + + + + + Page Redirection + + + If you are not redirected automatically, follow the $(mkRelFile "README.txt")) $ S.concat @@ -514,7 +514,7 @@ resolvePackageEntry menv projRoot pe = do subs -> mapM (resolveDir entryRoot) subs case peValidWanted pe of Nothing -> return () - Just _ -> $logWarn "Warning: you are using the deprecated valid-wanted field. You should instead use extra-dep. See: http://docs.haskellstack.org/en/stable/yaml_configuration.html#packages" + Just _ -> $logWarn "Warning: you are using the deprecated valid-wanted field. You should instead use extra-dep. See: http://docs.haskellstack.org/en/stable/yaml_configuration/#packages" return $ map (, not $ peExtraDep pe) paths -- | Resolve a PackageLocation into a path, downloading and cloning as @@ -726,7 +726,7 @@ getDefaultUserConfigPath stackRoot = do liftIO $ S.writeFile (toFilePath path) $ S.concat [ "# This file contains default non-project-specific settings for 'stack', used\n" , "# in all projects. For more information about stack's configuration, see\n" - , "# http://docs.haskellstack.org/en/stable/yaml_configuration.html\n" + , "# http://docs.haskellstack.org/en/stable/yaml_configuration/\n" , "#\n" , Yaml.encode (mempty :: Object) ] return path diff --git a/src/Stack/Init.hs b/src/Stack/Init.hs index c71ecda940..7caacf93aa 100644 --- a/src/Stack/Init.hs +++ b/src/Stack/Init.hs @@ -120,7 +120,7 @@ renderStackYaml p = _ -> assert False $ B.byteString $ Yaml.encode p where renderObject o = - B.byteString "# For more information, see: http://docs.haskellstack.org/en/stable/yaml_configuration.html\n\n" <> + B.byteString "# For more information, see: http://docs.haskellstack.org/en/stable/yaml_configuration/\n\n" <> F.foldMap (goComment o) comments <> goOthers (o `HM.difference` HM.fromList comments) <> B.byteString @@ -175,7 +175,7 @@ getSnapshots' = $logError "" $logError "You can try again, or create your stack.yaml file by hand. See:" $logError "" - $logError " http://docs.haskellstack.org/en/stable/yaml_configuration.html" + $logError " http://docs.haskellstack.org/en/stable/yaml_configuration/" $logError "" $logError $ "Exception was: " <> T.pack (show e) return Nothing diff --git a/src/Stack/Setup.hs b/src/Stack/Setup.hs index e8fccf9896..ccd9be9ad7 100644 --- a/src/Stack/Setup.hs +++ b/src/Stack/Setup.hs @@ -158,7 +158,7 @@ instance Show SetupException where [ "The GHC located at " , toFilePath ghc , " failed to compile a sanity check. Please see:\n\n" - , " http://docs.haskellstack.org/en/stable/install_and_upgrade.html\n\n" + , " http://docs.haskellstack.org/en/stable/install_and_upgrade/\n\n" , "for more information. Exception was:\n" , show e ] diff --git a/src/Stack/Types/Config.hs b/src/Stack/Types/Config.hs index 8c6b02cf6d..c8fc55361b 100644 --- a/src/Stack/Types/Config.hs +++ b/src/Stack/Types/Config.hs @@ -1087,7 +1087,7 @@ instance Show ConfigException where , toFilePath configFile , "':\n" , show exception - , "\nSee http://docs.haskellstack.org/en/stable/yaml_configuration.html." + , "\nSee http://docs.haskellstack.org/en/stable/yaml_configuration/." ] show (ParseResolverException t) = concat [ "Invalid resolver value: "