README.rst
61 lines
| 1.6 KiB
| text/x-rst
|
RstLexer
/ docs / README.rst
Paul Ivanov
|
r12939 | IPython Documentation | ||
--------------------- | ||||
fperez
|
r0 | |||
Matthias Bussonnier
|
r22667 | This directory contains the majority of the documentation for IPython. | ||
Paul Ivanov
|
r12939 | |||
Doug Latornell
|
r24060 | |||
Matthias Bussonnier
|
r20903 | Deploy docs | ||
----------- | ||||
Matthias Bussonnier
|
r22667 | Documentation is automatically deployed on ReadTheDocs on every push or merged | ||
Pull requests. | ||||
Matthias Bussonnier
|
r20903 | |||
Paul Ivanov
|
r12939 | Requirements | ||
------------ | ||||
Doug Latornell
|
r24060 | |||
The documentation must be built using Python 3. | ||||
Paul Ivanov
|
r12939 | The following tools are needed to build the documentation: | ||
Matthias Bussonnier
|
r22667 | - sphinx | ||
Doug Latornell
|
r24060 | - sphinx_rtd_theme | ||
Paul Ivanov
|
r12939 | |||
On Debian-based systems, you should be able to run:: | ||||
Doug Latornell
|
r24060 | sudo apt-get install python3-sphinx python3-sphinx-rtd-theme | ||
In a conda environment, you can use:: | ||||
conda install sphinx sphinx_rtd_theme | ||||
In a Python 3 ``venv``, you should be able to run:: | ||||
pip install -U sphinx sphinx_rtd_theme | ||||
Build Commands | ||||
-------------- | ||||
Paul Ivanov
|
r12939 | |||
The documentation gets built using ``make``, and comes in several flavors. | ||||
Matthias Bussonnier
|
r22667 | ``make html`` - build the API and narrative documentation web pages, this is | ||
the default ``make`` target, so running just ``make`` is equivalent to ``make | ||||
html``. | ||||
Paul Ivanov
|
r12939 | |||
Matthias Bussonnier
|
r22667 | ``make html_noapi`` - same as above, but without running the auto-generated API | ||
docs. When you are working on the narrative documentation, the most time | ||||
Paul Ivanov
|
r12939 | consuming portion of the build process is the processing and rending of the | ||
API documentation. This build target skips that. | ||||
``make pdf`` will compile a pdf from the documentation. | ||||
You can run ``make help`` to see information on all possible make targets. | ||||
Doug Latornell
|
r24061 | |||
Continuous Integration | ||||
---------------------- | ||||
Documentation builds are included in the Travis-CI continuous integration process, | ||||
so you can see the results of the docs build for any pull request at | ||||
https://travis-ci.org/ipython/ipython/pull_requests. | ||||