Skip to content

Commit 4ff336c

Browse files
jreklundjreklund
committed
Change into minimal makefile for Sphinx. Updating manual to depend on Python 3.
1 parent 3eea893 commit 4ff336c

4 files changed

Lines changed: 80 additions & 136 deletions

File tree

‎user_guide_src/Makefile‎

Lines changed: 13 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,20 @@
1-
# Makefile for Sphinx documentation
1+
# Minimal makefile for Sphinx documentation
22
#
33

4-
# You can set these variables from the command line.
5-
SPHINXOPTS =
6-
SPHINXBUILD = sphinx-build
7-
PAPER =
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
89
BUILDDIR = build
910

10-
# Internal variables.
11-
PAPEROPT_a4 = -D latex_paper_size=a4
12-
PAPEROPT_letter = -D latex_paper_size=letter
13-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
14-
15-
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest ghpages
16-
11+
# Put it first so that "make" without argument is like "make help".
1712
help:
18-
@echo "Please use \`make <target>' where <target> is one of"
19-
@echo " html to make standalone HTML files"
20-
@echo " dirhtml to make HTML files named index.html in directories"
21-
@echo " singlehtml to make a single large HTML file"
22-
@echo " pickle to make pickle files"
23-
@echo " json to make JSON files"
24-
@echo " htmlhelp to make HTML files and a HTML help project"
25-
@echo " qthelp to make HTML files and a qthelp project"
26-
@echo " devhelp to make HTML files and a Devhelp project"
27-
@echo " epub to make an epub"
28-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
29-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
30-
@echo " text to make text files"
31-
@echo " man to make manual pages"
32-
@echo " changes to make an overview of all changed/added/deprecated items"
33-
@echo " linkcheck to check all external links for integrity"
34-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
35-
36-
clean:
37-
-rm -rf $(BUILDDIR)/*
38-
39-
html:
40-
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
41-
@echo
42-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
43-
44-
dirhtml:
45-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
46-
@echo
47-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
48-
49-
singlehtml:
50-
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
51-
@echo
52-
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
53-
54-
pickle:
55-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
56-
@echo
57-
@echo "Build finished; now you can process the pickle files."
58-
59-
json:
60-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
61-
@echo
62-
@echo "Build finished; now you can process the JSON files."
63-
64-
htmlhelp:
65-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
66-
@echo
67-
@echo "Build finished; now you can run HTML Help Workshop with the" \
68-
".hhp project file in $(BUILDDIR)/htmlhelp."
69-
70-
qthelp:
71-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
72-
@echo
73-
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
74-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
75-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/CodeIgniter.qhcp"
76-
@echo "To view the help file:"
77-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/CodeIgniter.qhc"
78-
79-
devhelp:
80-
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
81-
@echo
82-
@echo "Build finished."
83-
@echo "To view the help file:"
84-
@echo "# mkdir -p $$HOME/.local/share/devhelp/CodeIgniter"
85-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/CodeIgniter"
86-
@echo "# devhelp"
87-
88-
epub:
89-
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
90-
@echo
91-
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
92-
93-
latex:
94-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
95-
@echo
96-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
97-
@echo "Run \`make' in that directory to run these through (pdf)latex" \
98-
"(use \`make latexpdf' here to do that automatically)."
99-
100-
latexpdf:
101-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
102-
@echo "Running LaTeX files through pdflatex..."
103-
make -C $(BUILDDIR)/latex all-pdf
104-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
105-
106-
text:
107-
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
108-
@echo
109-
@echo "Build finished. The text files are in $(BUILDDIR)/text."
110-
111-
man:
112-
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
113-
@echo
114-
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
115-
116-
changes:
117-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
118-
@echo
119-
@echo "The overview file is in $(BUILDDIR)/changes."
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
12014

121-
linkcheck:
122-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
123-
@echo
124-
@echo "Link check complete; look for any errors in the above output " \
125-
"or in $(BUILDDIR)/linkcheck/output.txt."
15+
.PHONY: help Makefile
12616

127-
doctest:
128-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
129-
@echo "Testing of doctests in the sources finished, look at the " \
130-
"results in $(BUILDDIR)/doctest/output.txt."
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎user_guide_src/README.rst‎

Lines changed: 65 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,26 +8,79 @@ Setup Instructions
88

99
The CodeIgniter user guide uses Sphinx to manage the documentation and
1010
output it to various formats. Pages are written in human-readable
11-
`ReStructured Text <http://sphinx.pocoo.org/rest.html>`_ format.
11+
`ReStructured Text <https://en.wikipedia.org/wiki/ReStructuredText>`_ format.
1212

1313
Prerequisites
1414
=============
1515

16-
Sphinx requires Python 2, which may already be installed if you are running OS X or Linux.
17-
You can confirm in a Terminal window by executing the ``python`` command
18-
without any parameters. It should load up and tell you which version you have
19-
installed. If you're not on 2.7+, go ahead and install 2.7+ from
20-
`Python.org <https://www.python.org/downloads/>`_
16+
Python
17+
------
18+
19+
Sphinx requires Python 3.5+, which may already be installed if you are running
20+
OS X or Linux. You can confirm in a Terminal window by executing ``python``
21+
or ``python3``.
22+
23+
.. code-block:: bash
24+
25+
python --version
26+
Python 2.7.17
27+
28+
python3 --version
29+
Python 3.6.9
30+
31+
If you're not on 3.5+, go ahead and install the latest 3.x version from
32+
`Python.org <https://www.python.org/downloads/>`_. Linux users should use their
33+
operative systems built in Package Managers to update.
34+
35+
pip
36+
---
37+
38+
Now that you have Python 3.x up and running, we will be installing
39+
`pip <https://pip.pypa.io/en/stable/>`_ (The Python Package Installer).
40+
41+
You can check if you have pip installed with ``pip`` or ``pip3``.
42+
As you can see pip follow the same naming convention as Python.
43+
Please take note that it should say ``python 3.x`` at the very end.
44+
45+
.. code-block:: bash
46+
47+
pip --version
48+
pip 9.0.1 from /usr/lib/python2.7/dist-packages (python 2.7)
49+
50+
pip3 --version
51+
pip 9.0.1 from /usr/lib/python3/dist-packages (python 3.6)
52+
53+
Linux
54+
^^^^^
55+
56+
`Installing pip/setuptools/wheel with Linux Package Managers
57+
<https://packaging.python.org/guides/installing-using-linux-tools/>`_
58+
59+
Other
60+
^^^^^
61+
62+
pip is already installed if you are using Python 3.4+ downloaded from
63+
`Python.org <https://www.python.org/downloads/>`_.
2164

2265
Installation
2366
============
2467

25-
1. Install `pip <https://packaging.python.org/guides/installing-using-linux-tools/>`_ (package manager).
26-
2. ``pip install "sphinx==1.8.5"``
27-
3. ``pip install "sphinxcontrib-phpdomain>=0.7.0"``
28-
4. Reboot your operating system
29-
5. ``cd user_guide_src``
30-
6. ``make html``
68+
Now we need to install Sphinx and it's dependencies. Choose ``pip`` or ``pip3``
69+
depending on operative system. After this step you need restart your Terminal
70+
window as Python won't find all applications we just installed othervise.
71+
72+
.. code-block:: bash
73+
74+
pip install -r user_guide_src/source/requirements.txt
75+
76+
pip3 install -r user_guide_src/source/requirements.txt
77+
78+
It's time to wrap things up and generate the documentation.
79+
80+
.. code-block:: bash
81+
82+
cd user_guide_src
83+
make html
3184
3285
Editing and Creating Documentation
3386
==================================

‎user_guide_src/source/general/ajax.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Fetch API
2929
jQuery
3030
======
3131

32-
For libraries like jQuery for example, it is not necessary to make explicit the sending of this header, because according to the official documentation <https://api.jquery.com/jquery.ajax/> it is a standard header for all requests ``$.ajax()``. But if you still want to force the shipment to not take risks, just do it as follows:
32+
For libraries like jQuery for example, it is not necessary to make explicit the sending of this header, because according to the `official documentation <https://api.jquery.com/jquery.ajax/>`_ it is a standard header for all requests ``$.ajax()``. But if you still want to force the shipment to not take risks, just do it as follows:
3333

3434
.. code-block:: javascript
3535

‎user_guide_src/source/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
sphinx==1.8.5
22
sphinxcontrib-phpdomain>=0.7.0
3+
docutils==0.16

0 commit comments

Comments
 (0)