Commit 664ef06d authored by lspitzner's avatar lspitzner

doc: Makefile, Add proper source link, Add to new-freeze

- Fix Makefile to work on arch where we need to use sphinx-build2
- README: mention python 2 and use Makefile
- html output now properly links to github source
- new-freeze documentation fixed for the --project-file case

fixes #4833, #4834 [ci skip]
parent 4e85e44b
...@@ -25,6 +25,14 @@ USERGUIDE_STAMP=dist/doc/users-guide/index.html ...@@ -25,6 +25,14 @@ USERGUIDE_STAMP=dist/doc/users-guide/index.html
SDIST_STAMP=dist/Cabal-$(VERSION).tar.gz SDIST_STAMP=dist/Cabal-$(VERSION).tar.gz
DISTLOC=dist/release DISTLOC=dist/release
DIST_STAMP=$(DISTLOC)/Cabal-$(VERSION).tar.gz DIST_STAMP=$(DISTLOC)/Cabal-$(VERSION).tar.gz
SPHINXCMD:=$(shell command -v sphinx-build2 2> /dev/null)
ifndef SPHINXCMD
SPHINXCMD:=$(shell command -v sphinx-build 2> /dev/null)
endif
ifndef SPHINXCMD
$(error "needs sphinx-build")
endif
COMMA=, COMMA=,
...@@ -54,7 +62,7 @@ SPHINX_HTML_OUTDIR=dist/doc/users-guide ...@@ -54,7 +62,7 @@ SPHINX_HTML_OUTDIR=dist/doc/users-guide
users-guide: $(USERGUIDE_STAMP) users-guide: $(USERGUIDE_STAMP)
$(USERGUIDE_STAMP) : doc/*.rst $(USERGUIDE_STAMP) : doc/*.rst
mkdir -p $(SPHINX_HTML_OUTDIR) mkdir -p $(SPHINX_HTML_OUTDIR)
sphinx-build doc $(SPHINX_HTML_OUTDIR) $(SPHINXCMD) doc $(SPHINX_HTML_OUTDIR)
docs: haddock users-guide docs: haddock users-guide
......
...@@ -11,14 +11,16 @@ http://cabal.readthedocs.io/ ...@@ -11,14 +11,16 @@ http://cabal.readthedocs.io/
### How to build it ### How to build it
* Currently requires python-2
* `> pip install sphinx` * `> pip install sphinx`
* `> pip install sphinx_rtd_theme` * `> pip install sphinx_rtd_theme`
* `> cd Cabal` * `> cd Cabal`
* `> sphinx-build doc html` * `> make clean users-guide`
* if you are missing any other dependencies, install them with `pip` as needed * if you are missing any other dependencies, install them with `pip` as needed
¯\\\_(ツ)_/¯ ¯\\\_(ツ)_/¯
* Python on Mac OS X dislikes `LC_CTYPE=UTF-8`, unset the env var in * Python on Mac OS X dislikes `LC_CTYPE=UTF-8`, unset the env var in
terminal preferences and instead set `LC_ALL=en_US.UTF-8` or something terminal preferences and instead set `LC_ALL=en_US.UTF-8` or something
* On archlinux, package `python2-sphinx` is sufficient.
### Caveats, for newcomers to RST from MD ### Caveats, for newcomers to RST from MD
RST does not allow you to skip section levels when nesting, like MD RST does not allow you to skip section levels when nesting, like MD
......
...@@ -67,6 +67,17 @@ html_static_path = ['images'] ...@@ -67,6 +67,17 @@ html_static_path = ['images']
# Convert quotes and dashes to typographically correct entities # Convert quotes and dashes to typographically correct entities
html_use_smartypants = True html_use_smartypants = True
html_show_copyright = True html_show_copyright = True
html_context = {
'source_url_prefix': "https://github.com/haskell/cabal/tree/master/Cabal/doc/",
"display_github": True,
"github_host": "github.com",
"github_user": "haskell",
"github_repo": 'cabal',
"github_version": "master/",
"conf_py_path": "Cabal/doc/",
"source_suffix": '.rst',
}
# If true, an OpenSearch description file will be output, and all pages will # If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the # contain a <link> tag referring to it. The value of this option must be the
......
...@@ -378,11 +378,15 @@ have to separate them with ``--``. ...@@ -378,11 +378,15 @@ have to separate them with ``--``.
cabal new-freeze cabal new-freeze
---------------- ----------------
``cabal new-freeze`` writes out a ``cabal.project.freeze`` file which ``cabal new-freeze`` writes out a **freeze file** which records all of
records all of the versions and flags which that are picked by the the versions and flags which that are picked by the solver under the
solver under the current index and flags. A ``cabal.project.freeze`` current index and flags. Default name of this file is
file has the same syntax as ``cabal.project`` and looks something like ``cabal.project.freeze`` but in combination with a
this: ``--project-file=my.project`` flag (see :ref:`project-file
<cmdoption-project-file>`)
the name will be ``my.project.freeze``.
A freeze file has the same syntax as ``cabal.project`` and looks
something like this:
.. highlight:: cabal .. highlight:: cabal
...@@ -632,6 +636,7 @@ package, and thus apply globally: ...@@ -632,6 +636,7 @@ package, and thus apply globally:
This option cannot be specified via a ``cabal.project`` file. This option cannot be specified via a ``cabal.project`` file.
.. _cmdoption-project-file:
.. option:: --project-file=FILE .. option:: --project-file=FILE
Specifies the name of the project file used to specify the Specifies the name of the project file used to specify the
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment