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
SDIST_STAMP=dist/Cabal-$(VERSION).tar.gz
DISTLOC=dist/release
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=,
......@@ -54,7 +62,7 @@ SPHINX_HTML_OUTDIR=dist/doc/users-guide
users-guide: $(USERGUIDE_STAMP)
$(USERGUIDE_STAMP) : doc/*.rst
mkdir -p $(SPHINX_HTML_OUTDIR)
sphinx-build doc $(SPHINX_HTML_OUTDIR)
$(SPHINXCMD) doc $(SPHINX_HTML_OUTDIR)
docs: haddock users-guide
......
......@@ -11,14 +11,16 @@ http://cabal.readthedocs.io/
### How to build it
* Currently requires python-2
* `> pip install sphinx`
* `> pip install sphinx_rtd_theme`
* `> cd Cabal`
* `> sphinx-build doc html`
* `> make clean users-guide`
* 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
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
RST does not allow you to skip section levels when nesting, like MD
......
......@@ -67,6 +67,17 @@ html_static_path = ['images']
# Convert quotes and dashes to typographically correct entities
html_use_smartypants = 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
# contain a <link> tag referring to it. The value of this option must be the
......
......@@ -378,11 +378,15 @@ have to separate them with ``--``.
cabal new-freeze
----------------
``cabal new-freeze`` writes out a ``cabal.project.freeze`` file which
records all of the versions and flags which that are picked by the
solver under the current index and flags. A ``cabal.project.freeze``
file has the same syntax as ``cabal.project`` and looks something like
this:
``cabal new-freeze`` writes out a **freeze file** which records all of
the versions and flags which that are picked by the solver under the
current index and flags. Default name of this file is
``cabal.project.freeze`` but in combination with a
``--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
......@@ -632,6 +636,7 @@ package, and thus apply globally:
This option cannot be specified via a ``cabal.project`` file.
.. _cmdoption-project-file:
.. option:: --project-file=FILE
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