##// END OF EJS Templates
Update docs/README.rst
Matthias Bussonnier -
Show More
@@ -1,64 +1,64 b''
1 IPython Documentation
1 IPython Documentation
2 ---------------------
2 ---------------------
3
3
4 This directory contains the majority of the documentation for IPython.
4 This directory contains the majority of the documentation for IPython.
5
5
6
6
7 Deploy docs
7 Deploy docs
8 -----------
8 -----------
9
9
10 Documentation is automatically deployed on ReadTheDocs on every push or merged
10 Documentation is automatically deployed on ReadTheDocs on every push or merged
11 Pull requests.
11 Pull requests.
12
12
13
13
14 Requirements
14 Requirements
15 ------------
15 ------------
16
16
17 The documentation must be built using Python 3.
17 The documentation must be built using Python 3.
18
18
19 In addition to :ref:``devinstall``,
19 In addition to :ref:`devinstall`,
20 the following tools are needed to build the documentation:
20 the following tools are needed to build the documentation:
21
21
22 - sphinx
22 - sphinx
23 - sphinx_rtd_theme
23 - sphinx_rtd_theme
24 - docrepr
24 - docrepr
25
25
26 In a conda environment, or a Python 3 ``venv``, you should be able to run::
26 In a conda environment, or a Python 3 ``venv``, you should be able to run::
27
27
28 cd ipython
28 cd ipython
29 pip install -U -r docs/requirements.txt
29 pip install -U -r docs/requirements.txt
30
30
31
31
32 Build Commands
32 Build Commands
33 --------------
33 --------------
34
34
35 The documentation gets built using ``make``, and comes in several flavors.
35 The documentation gets built using ``make``, and comes in several flavors.
36
36
37 ``make html`` - build the API and narrative documentation web pages, this is
37 ``make html`` - build the API and narrative documentation web pages, this is
38 the default ``make`` target, so running just ``make`` is equivalent to ``make
38 the default ``make`` target, so running just ``make`` is equivalent to ``make
39 html``.
39 html``.
40
40
41 ``make html_noapi`` - same as above, but without running the auto-generated API
41 ``make html_noapi`` - same as above, but without running the auto-generated API
42 docs. When you are working on the narrative documentation, the most time
42 docs. When you are working on the narrative documentation, the most time
43 consuming portion of the build process is the processing and rendering of the
43 consuming portion of the build process is the processing and rendering of the
44 API documentation. This build target skips that.
44 API documentation. This build target skips that.
45
45
46 ``make pdf`` will compile a pdf from the documentation.
46 ``make pdf`` will compile a pdf from the documentation.
47
47
48 You can run ``make help`` to see information on all possible make targets.
48 You can run ``make help`` to see information on all possible make targets.
49
49
50 To save time,
50 To save time,
51 the make targets above only process the files that have been changed since the
51 the make targets above only process the files that have been changed since the
52 previous docs build.
52 previous docs build.
53 To remove the previous docs build you can use ``make clean``.
53 To remove the previous docs build you can use ``make clean``.
54 You can also combine ``clean`` with other `make` commands;
54 You can also combine ``clean`` with other `make` commands;
55 for example,
55 for example,
56 ``make clean html`` will do a complete rebuild of the docs or ``make clean pdf`` will do a complete build of the pdf.
56 ``make clean html`` will do a complete rebuild of the docs or ``make clean pdf`` will do a complete build of the pdf.
57
57
58
58
59 Continuous Integration
59 Continuous Integration
60 ----------------------
60 ----------------------
61
61
62 Documentation builds are included in the Travis-CI continuous integration process,
62 Documentation builds are included in the Travis-CI continuous integration process,
63 so you can see the results of the docs build for any pull request at
63 so you can see the results of the docs build for any pull request at
64 https://travis-ci.org/ipython/ipython/pull_requests.
64 https://travis-ci.org/ipython/ipython/pull_requests.
General Comments 0
You need to be logged in to leave comments. Login now