Skip to content

updating developer docs #8544

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Apr 28, 2017
Merged

updating developer docs #8544

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
83129fa
updating developer docs
choldgraf Apr 27, 2017
0baccc7
addressing comments
choldgraf Apr 28, 2017
530c62d
Update documenting_mpl.rst
choldgraf Apr 28, 2017
23f4757
Update documenting_mpl.rst
choldgraf Apr 28, 2017
5efe61c
Update documenting_mpl.rst
choldgraf Apr 28, 2017
ff1b20e
Update documenting_mpl.rst
choldgraf Apr 28, 2017
c6866a0
Update documenting_mpl.rst
choldgraf Apr 28, 2017
d73ff15
fixing link
choldgraf Apr 28, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
addressing comments
  • Loading branch information
@choldgraf
choldgraf authored Apr 28, 2017
commit 0baccc76b3f87f22129c42afa59b5e86df81ff98
12 changes: 7 additions & 5 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,21 +27,23 @@ as well as listed below:
.. note::

* You'll need a minimal working latex distribution for many examples to run.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LaTeX

* Graphviz is not pip-installable so you need to install this on your own.
* `Graphviz <http://graphviz.readthedocs.io/en/latest/manual.html>`_ is not pip-installable so you need
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link is not to the right graphviz. It is here.

to install this on your own. This is straightforward with something like
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure the conda reference is helpful here 'cause it's not really contextualized.

the `anaconda distribution <https://anaconda.org/>`_.

General structure
-----------------

All documentation is built from the :file:`doc/` directory. This folder contains both
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One case of "directory" and many of "folder"; I think we should be consistent about it (preferring directory, myself.)

``.rst`` files that contains pages in the documentation, folders that contain more
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

contain pages

``.rst`` files, and configuration for Sphinx.
``.rst`` files, and configuration files for Sphinx.

.. note::

An exception to this are the folders :file:`gallery` and :file:`tutorials`, which
exist in the root folder. These contain python files that are built by ``sphinx-gallery``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Python

When the docs are built, folders of the same name will be generated inside of :file:`docs/`.
These can be safely deleted.
The generated folders :file:`docs/gallery` and :file:`docs/tutorials` can be safely deleted.

The configuration file for Sphinx is in :file:`doc/conf.py`. It controls which folders
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is :file:doc/conf.py

sphinx parses, how the docs are built, and how the extensions are used.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sphinx

Expand All @@ -62,9 +64,9 @@ or::
There are many other flags you can pass to ``make.py``, and you can see the
full list inside that file. Here are two useful ones:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or run ./make.py --help? (maybe?)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I put this in the flags section


* ``clean`` will delete the built sphinx files. Call if you're getting strange
* ``clean`` will delete the built sphinx files. Use this command if you're getting strange
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sphinx

errors about missing paths or broken links, particularly if you move files around.
* ``latex`` builds a pdf of the documentation
* ``latex`` builds a pdf of the documentation.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PDF


In addition, these are useful flags:

Expand Down