[yt-svn] commit/yt: 5 new changesets
commits-noreply at bitbucket.org
commits-noreply at bitbucket.org
Thu May 8 20:48:50 PDT 2014
5 new commits in yt:
https://bitbucket.org/yt_analysis/yt/commits/b6e94a4fe0e7/
Changeset: b6e94a4fe0e7
Branch: yt-3.0
User: chummels
Date: 2014-05-09 02:08:33
Summary: Updating the build the docs documentation to reflect the changes in 3.0
Affected #: 1 file
diff -r b6bbd6601ea3f3fcdce2568d2383f52fb1876763 -r b6e94a4fe0e7fcb5ced504db2b3fee1a489032f7 doc/source/developing/building_the_docs.rst
--- a/doc/source/developing/building_the_docs.rst
+++ b/doc/source/developing/building_the_docs.rst
@@ -1,8 +1,8 @@
.. _docs_build:
-=================
-Building the Docs
-=================
+==========================
+Building the Documentation
+==========================
The yt documentation makes heavy use of the sphinx documentation automation
suite. Sphinx, written in python, was originally created for the documentation
@@ -11,13 +11,64 @@
While much of the yt documentation is static text, we make heavy use of
cross-referencing with API documentation that is automatically generated at
-build time by sphinx. We also use sphinx to run code snippets and embed
-resulting images and example data.
+build time by sphinx. We also use sphinx to run code snippets (e.g. the
+cookbook and the notebooks) and embed resulting images and example data.
-yt Sphinx extensions
---------------------
+Quick versus full documentation builds
+--------------------------------------
-The documentation makes heavy use of custom sphinx extensions to transform
+Building the entire set of yt documentation is a laborious task, since you
+need to have a large number of packages in order to successfully execute
+and render all of the notebooks and yt recipes drawing from every corner
+of the yt source. As an quick alternative, one can do a ``quick`` build
+of the documentation, which eschews the need for downloading all of these
+dependencies, but it only produces the static docs. The static docs do
+not include the cookbook outputs and the notebooks, but this is good
+enough for most cases of people testing out whether or not their documentation
+contributions look OK before submitting them to the yt repository.
+
+If you want to create the full documentation locally, then you'll need
+to follow the instructions for building the ``full`` docs, so that you can
+dynamically execute and render the cookbook recipes, the notebooks, etc.
+
+Building the docs (quick)
+-------------------------
+
+You will need to have the yt repository available on your computer, which
+is done by default if you have yt installed. In addition, you need a
+current version of Sphinx_ (1.1.3) documentation software installed.
+
+In order to tell sphinx not to do all of the dynamical building, you must
+set the ``$READTHEDOCS`` environment variable to be True by typing this at
+the command line:
+
+.. code-block:: bash
+
+ export READTHEDOCS=True # for bash
+ setenv READTHEDOCS True # for csh
+
+This variable is set for automated builds on the free ReadTheDocs service but
+can be used by anyone to force a quick, minimal build.
+
+Now all you need to do is execute sphinx on the yt doc source. Go to the
+documentation directory and build the docs:
+
+.. code-block:: bash
+
+ cd $YT_DEST/src/yt-hg/doc
+ make html
+
+This will produce an html version of the documentation locally in the
+``$YT_DEST/src/yt-hg/doc/build/html`` directory. You can now go there and open
+up ``index.html`` or whatever file you wish in your web browser.
+
+Building the docs (full)
+------------------------
+
+As alluded to earlier, building the full documentation is a bit more involved
+than simply building the static documentation.
+
+The full documentation makes heavy use of custom sphinx extensions to transform
recipes, notebooks, and inline code snippets into python scripts, IPython_
notebooks, or notebook cells that are executed when the docs are built.
@@ -30,12 +81,9 @@
.. _runipy: https://github.com/paulgb/runipy
.. _IPython: http://ipython.org/
-Dependencies
-------------
-
-To build the docs, you will need yt, IPython, runipy, and all supplementary yt
-analysis modules installed. The following dependencies were used to generate the
-yt documentation during the release of yt 2.6 in late 2013.
+To build the full documentation, you will need yt, IPython, runipy, and all
+supplementary yt analysis modules installed. The following dependencies were
+used to generate the yt documentation during the release of yt 2.6 in late 2013.
- Sphinx_ 1.1.3
- IPython_ 1.1
@@ -58,49 +106,32 @@
<http://yt-project.org/data/>`_, including the larger datasets that are not used
in the answer tests.
-Building the docs
------------------
-
-First, you will need to ensure that your testing configuration is properly
+You will need to ensure that your testing configuration is properly
configured and that all of the yt test data is in the testing directory. See
:ref:`run_answer_testing` for more details on how to set up the testing
configuration.
-Next, clone the yt-doc repository, navigate to the root of the repository, and
-do :code:`make html`.
+Now that you have everything set up properly, go to the documentation directory
+and build it using sphinx:
.. code-block:: bash
- hg clone https://bitbucket.org/yt_analysis/yt-doc ./yt-doc
- cd yt-doc
+ cd $YT_DEST/src/yt-hg/doc
make html
If all of the dependencies are installed and all of the test data is in the
-testing directory, this should churn away for a while and eventually generate a
-docs build. This process is lengthy but shouldn't last more than an hour. We
-suggest setting :code:`suppressStreamLogging = True` in your yt configuration
-(See :ref:`configuration-file`) to suppress large amounts of debug output from
+testing directory, this should churn away for a while (~ 1 hour) and
+eventually generate a docs build. We suggest setting
+:code:`suppressStreamLogging = True` in your yt configuration (See
+:ref:`configuration-file`) to suppress large amounts of debug output from
yt.
To clean the docs build, use :code:`make clean`. By default, :code:`make clean`
will not delete the autogenerated API docs, so use :code:`make fullclean` to
delete those as well.
-
-Quick docs builds
------------------
-
-Clearly, building the complete docs is something of an undertaking. If you are
-adding new static content building the complete docs build is probably
-overkill. To skip some of the lengthier operations, you can do the following
-from the bash prompt:
-
-.. code-block:: bash
-
- export READTHEDOCS=True
-
-This variable is set for automated builds on the free ReadTheDocs service but
-can be used by anyone to force a quick, minimal build.
+Building the docs (hybrid)
+--------------------------
It's also possible to create a custom sphinx build that builds a restricted set
of notebooks or scripts. This can be accomplished by editing the Sphinx
https://bitbucket.org/yt_analysis/yt/commits/0affe54533a4/
Changeset: 0affe54533a4
Branch: yt-3.0
User: chummels
Date: 2014-05-09 02:15:52
Summary: Modifying the developing page to reflect the fact that there is no longer a yt-doc repo.
Affected #: 1 file
diff -r b6e94a4fe0e7fcb5ced504db2b3fee1a489032f7 -r 0affe54533a4c75b1956d6d0bfd7b5d3242d41e4 doc/source/developing/developing.rst
--- a/doc/source/developing/developing.rst
+++ b/doc/source/developing/developing.rst
@@ -215,12 +215,16 @@
++++++++++++++++++++++++++
The process for writing documentation is identical to the above, except that
-instead of ``yt_analysis/yt`` you should be forking and pushing to
-``yt_analysis/yt-doc``. All the source for the documentation is written in
+you're modifying source files in the doc directory (i.e. ``$YT_DEST/src/yt-hg/doc``)
+instead of the src directory (i.e. ``$YT_DEST/src/yt-hg/yt``) of the yt repository.
+All the source for the documentation is written in
`Sphinx <http://sphinx-doc.org/>`_, which uses ReST for markup.
Cookbook recipes go in ``source/cookbook/`` and must be added to one of the
-``.rst`` files in that directory.
+``.rst`` files in that directory.
+
+For more information on how to build the documentation to make sure it looks
+the way you expect it to after modifying it, see :ref:`docs_build`.
How To Get The Source Code For Editing
--------------------------------------
https://bitbucket.org/yt_analysis/yt/commits/beadff5d7f48/
Changeset: beadff5d7f48
Branch: yt-3.0
User: chummels
Date: 2014-05-09 02:21:31
Summary: Updating the docs to reflect the fact that the docs live in the main repo.
Affected #: 3 files
diff -r 0affe54533a4c75b1956d6d0bfd7b5d3242d41e4 -r beadff5d7f4862dc54d11587df6dc434c2560c84 doc/source/cookbook/index.rst
--- a/doc/source/cookbook/index.rst
+++ b/doc/source/cookbook/index.rst
@@ -21,9 +21,8 @@
If you want to take a look at more complex recipes, or submit your own,
check out the `yt Hub <http://hub.yt-project.org>`_.
-.. note:: To contribute your own recipes, please
- `fork <http://bitbucket.org/yt_analysis/yt-doc/fork>`_
- the documentation repository!
+.. note:: To contribute your own recipes, please follow the instructions
+ on how to contribute documentation code: :ref:`writing_documentation`.
Example Scripts
---------------
diff -r 0affe54533a4c75b1956d6d0bfd7b5d3242d41e4 -r beadff5d7f4862dc54d11587df6dc434c2560c84 doc/source/developing/developing.rst
--- a/doc/source/developing/developing.rst
+++ b/doc/source/developing/developing.rst
@@ -211,6 +211,8 @@
#. Update your pull request by visiting
https://bitbucket.org/YourUsername/yt/pull-request/new
+.. _writing_documentation:
+
How to Write Documentation
++++++++++++++++++++++++++
diff -r 0affe54533a4c75b1956d6d0bfd7b5d3242d41e4 -r beadff5d7f4862dc54d11587df6dc434c2560c84 doc/source/developing/intro.rst
--- a/doc/source/developing/intro.rst
+++ b/doc/source/developing/intro.rst
@@ -66,10 +66,8 @@
typo or grammatical fixes, adding a FAQ, or increasing coverage of
functionality, it would be very helpful if you wanted to help out.
-The easiest way to help out is to fork the repository:
-
-http://hg.yt-project.org/yt-doc/fork
-
+The easiest way to help out is to fork the main yt repository (where
+the documentation lives in the ``$YT_DEST/src/yt-hg/doc`` directory,
and then make your changes in your own fork. When you are done, issue a pull
request through the website for your new fork, and we can comment back and
forth and eventually accept your changes.
https://bitbucket.org/yt_analysis/yt/commits/f74e2bccdd85/
Changeset: f74e2bccdd85
Branch: yt-3.0
User: chummels
Date: 2014-05-09 02:22:21
Summary: Merging.
Affected #: 4 files
diff -r 49bd5c1c9d59d9dcf42e26b9b88c9c831018c002 -r f74e2bccdd856060132d82d31568cc0376cb93c5 doc/source/cookbook/index.rst
--- a/doc/source/cookbook/index.rst
+++ b/doc/source/cookbook/index.rst
@@ -21,9 +21,8 @@
If you want to take a look at more complex recipes, or submit your own,
check out the `yt Hub <http://hub.yt-project.org>`_.
-.. note:: To contribute your own recipes, please
- `fork <http://bitbucket.org/yt_analysis/yt-doc/fork>`_
- the documentation repository!
+.. note:: To contribute your own recipes, please follow the instructions
+ on how to contribute documentation code: :ref:`writing_documentation`.
Example Scripts
---------------
diff -r 49bd5c1c9d59d9dcf42e26b9b88c9c831018c002 -r f74e2bccdd856060132d82d31568cc0376cb93c5 doc/source/developing/building_the_docs.rst
--- a/doc/source/developing/building_the_docs.rst
+++ b/doc/source/developing/building_the_docs.rst
@@ -1,8 +1,8 @@
.. _docs_build:
-=================
-Building the Docs
-=================
+==========================
+Building the Documentation
+==========================
The yt documentation makes heavy use of the sphinx documentation automation
suite. Sphinx, written in python, was originally created for the documentation
@@ -11,13 +11,64 @@
While much of the yt documentation is static text, we make heavy use of
cross-referencing with API documentation that is automatically generated at
-build time by sphinx. We also use sphinx to run code snippets and embed
-resulting images and example data.
+build time by sphinx. We also use sphinx to run code snippets (e.g. the
+cookbook and the notebooks) and embed resulting images and example data.
-yt Sphinx extensions
---------------------
+Quick versus full documentation builds
+--------------------------------------
-The documentation makes heavy use of custom sphinx extensions to transform
+Building the entire set of yt documentation is a laborious task, since you
+need to have a large number of packages in order to successfully execute
+and render all of the notebooks and yt recipes drawing from every corner
+of the yt source. As an quick alternative, one can do a ``quick`` build
+of the documentation, which eschews the need for downloading all of these
+dependencies, but it only produces the static docs. The static docs do
+not include the cookbook outputs and the notebooks, but this is good
+enough for most cases of people testing out whether or not their documentation
+contributions look OK before submitting them to the yt repository.
+
+If you want to create the full documentation locally, then you'll need
+to follow the instructions for building the ``full`` docs, so that you can
+dynamically execute and render the cookbook recipes, the notebooks, etc.
+
+Building the docs (quick)
+-------------------------
+
+You will need to have the yt repository available on your computer, which
+is done by default if you have yt installed. In addition, you need a
+current version of Sphinx_ (1.1.3) documentation software installed.
+
+In order to tell sphinx not to do all of the dynamical building, you must
+set the ``$READTHEDOCS`` environment variable to be True by typing this at
+the command line:
+
+.. code-block:: bash
+
+ export READTHEDOCS=True # for bash
+ setenv READTHEDOCS True # for csh
+
+This variable is set for automated builds on the free ReadTheDocs service but
+can be used by anyone to force a quick, minimal build.
+
+Now all you need to do is execute sphinx on the yt doc source. Go to the
+documentation directory and build the docs:
+
+.. code-block:: bash
+
+ cd $YT_DEST/src/yt-hg/doc
+ make html
+
+This will produce an html version of the documentation locally in the
+``$YT_DEST/src/yt-hg/doc/build/html`` directory. You can now go there and open
+up ``index.html`` or whatever file you wish in your web browser.
+
+Building the docs (full)
+------------------------
+
+As alluded to earlier, building the full documentation is a bit more involved
+than simply building the static documentation.
+
+The full documentation makes heavy use of custom sphinx extensions to transform
recipes, notebooks, and inline code snippets into python scripts, IPython_
notebooks, or notebook cells that are executed when the docs are built.
@@ -30,12 +81,9 @@
.. _runipy: https://github.com/paulgb/runipy
.. _IPython: http://ipython.org/
-Dependencies
-------------
-
-To build the docs, you will need yt, IPython, runipy, and all supplementary yt
-analysis modules installed. The following dependencies were used to generate the
-yt documentation during the release of yt 2.6 in late 2013.
+To build the full documentation, you will need yt, IPython, runipy, and all
+supplementary yt analysis modules installed. The following dependencies were
+used to generate the yt documentation during the release of yt 2.6 in late 2013.
- Sphinx_ 1.1.3
- IPython_ 1.1
@@ -58,49 +106,32 @@
<http://yt-project.org/data/>`_, including the larger datasets that are not used
in the answer tests.
-Building the docs
------------------
-
-First, you will need to ensure that your testing configuration is properly
+You will need to ensure that your testing configuration is properly
configured and that all of the yt test data is in the testing directory. See
:ref:`run_answer_testing` for more details on how to set up the testing
configuration.
-Next, clone the yt-doc repository, navigate to the root of the repository, and
-do :code:`make html`.
+Now that you have everything set up properly, go to the documentation directory
+and build it using sphinx:
.. code-block:: bash
- hg clone https://bitbucket.org/yt_analysis/yt-doc ./yt-doc
- cd yt-doc
+ cd $YT_DEST/src/yt-hg/doc
make html
If all of the dependencies are installed and all of the test data is in the
-testing directory, this should churn away for a while and eventually generate a
-docs build. This process is lengthy but shouldn't last more than an hour. We
-suggest setting :code:`suppressStreamLogging = True` in your yt configuration
-(See :ref:`configuration-file`) to suppress large amounts of debug output from
+testing directory, this should churn away for a while (~ 1 hour) and
+eventually generate a docs build. We suggest setting
+:code:`suppressStreamLogging = True` in your yt configuration (See
+:ref:`configuration-file`) to suppress large amounts of debug output from
yt.
To clean the docs build, use :code:`make clean`. By default, :code:`make clean`
will not delete the autogenerated API docs, so use :code:`make fullclean` to
delete those as well.
-
-Quick docs builds
------------------
-
-Clearly, building the complete docs is something of an undertaking. If you are
-adding new static content building the complete docs build is probably
-overkill. To skip some of the lengthier operations, you can do the following
-from the bash prompt:
-
-.. code-block:: bash
-
- export READTHEDOCS=True
-
-This variable is set for automated builds on the free ReadTheDocs service but
-can be used by anyone to force a quick, minimal build.
+Building the docs (hybrid)
+--------------------------
It's also possible to create a custom sphinx build that builds a restricted set
of notebooks or scripts. This can be accomplished by editing the Sphinx
diff -r 49bd5c1c9d59d9dcf42e26b9b88c9c831018c002 -r f74e2bccdd856060132d82d31568cc0376cb93c5 doc/source/developing/developing.rst
--- a/doc/source/developing/developing.rst
+++ b/doc/source/developing/developing.rst
@@ -211,16 +211,22 @@
#. Update your pull request by visiting
https://bitbucket.org/YourUsername/yt/pull-request/new
+.. _writing_documentation:
+
How to Write Documentation
++++++++++++++++++++++++++
The process for writing documentation is identical to the above, except that
-instead of ``yt_analysis/yt`` you should be forking and pushing to
-``yt_analysis/yt-doc``. All the source for the documentation is written in
+you're modifying source files in the doc directory (i.e. ``$YT_DEST/src/yt-hg/doc``)
+instead of the src directory (i.e. ``$YT_DEST/src/yt-hg/yt``) of the yt repository.
+All the source for the documentation is written in
`Sphinx <http://sphinx-doc.org/>`_, which uses ReST for markup.
Cookbook recipes go in ``source/cookbook/`` and must be added to one of the
-``.rst`` files in that directory.
+``.rst`` files in that directory.
+
+For more information on how to build the documentation to make sure it looks
+the way you expect it to after modifying it, see :ref:`docs_build`.
How To Get The Source Code For Editing
--------------------------------------
diff -r 49bd5c1c9d59d9dcf42e26b9b88c9c831018c002 -r f74e2bccdd856060132d82d31568cc0376cb93c5 doc/source/developing/intro.rst
--- a/doc/source/developing/intro.rst
+++ b/doc/source/developing/intro.rst
@@ -66,10 +66,8 @@
typo or grammatical fixes, adding a FAQ, or increasing coverage of
functionality, it would be very helpful if you wanted to help out.
-The easiest way to help out is to fork the repository:
-
-http://hg.yt-project.org/yt-doc/fork
-
+The easiest way to help out is to fork the main yt repository (where
+the documentation lives in the ``$YT_DEST/src/yt-hg/doc`` directory,
and then make your changes in your own fork. When you are done, issue a pull
request through the website for your new fork, and we can comment back and
forth and eventually accept your changes.
https://bitbucket.org/yt_analysis/yt/commits/a14a150c7c81/
Changeset: a14a150c7c81
Branch: yt-3.0
User: ngoldbaum
Date: 2014-05-09 05:48:39
Summary: Merged in chummels/yt/yt-3.0 (pull request #889)
Updating documentation to reflect there is no yt-doc repo
Affected #: 4 files
diff -r 7562cc292b716c0f95050c365291c090501e91f2 -r a14a150c7c81850df81346162bdaff271e77eb50 doc/source/cookbook/index.rst
--- a/doc/source/cookbook/index.rst
+++ b/doc/source/cookbook/index.rst
@@ -21,9 +21,8 @@
If you want to take a look at more complex recipes, or submit your own,
check out the `yt Hub <http://hub.yt-project.org>`_.
-.. note:: To contribute your own recipes, please
- `fork <http://bitbucket.org/yt_analysis/yt-doc/fork>`_
- the documentation repository!
+.. note:: To contribute your own recipes, please follow the instructions
+ on how to contribute documentation code: :ref:`writing_documentation`.
Example Scripts
---------------
diff -r 7562cc292b716c0f95050c365291c090501e91f2 -r a14a150c7c81850df81346162bdaff271e77eb50 doc/source/developing/building_the_docs.rst
--- a/doc/source/developing/building_the_docs.rst
+++ b/doc/source/developing/building_the_docs.rst
@@ -1,8 +1,8 @@
.. _docs_build:
-=================
-Building the Docs
-=================
+==========================
+Building the Documentation
+==========================
The yt documentation makes heavy use of the sphinx documentation automation
suite. Sphinx, written in python, was originally created for the documentation
@@ -11,13 +11,64 @@
While much of the yt documentation is static text, we make heavy use of
cross-referencing with API documentation that is automatically generated at
-build time by sphinx. We also use sphinx to run code snippets and embed
-resulting images and example data.
+build time by sphinx. We also use sphinx to run code snippets (e.g. the
+cookbook and the notebooks) and embed resulting images and example data.
-yt Sphinx extensions
---------------------
+Quick versus full documentation builds
+--------------------------------------
-The documentation makes heavy use of custom sphinx extensions to transform
+Building the entire set of yt documentation is a laborious task, since you
+need to have a large number of packages in order to successfully execute
+and render all of the notebooks and yt recipes drawing from every corner
+of the yt source. As an quick alternative, one can do a ``quick`` build
+of the documentation, which eschews the need for downloading all of these
+dependencies, but it only produces the static docs. The static docs do
+not include the cookbook outputs and the notebooks, but this is good
+enough for most cases of people testing out whether or not their documentation
+contributions look OK before submitting them to the yt repository.
+
+If you want to create the full documentation locally, then you'll need
+to follow the instructions for building the ``full`` docs, so that you can
+dynamically execute and render the cookbook recipes, the notebooks, etc.
+
+Building the docs (quick)
+-------------------------
+
+You will need to have the yt repository available on your computer, which
+is done by default if you have yt installed. In addition, you need a
+current version of Sphinx_ (1.1.3) documentation software installed.
+
+In order to tell sphinx not to do all of the dynamical building, you must
+set the ``$READTHEDOCS`` environment variable to be True by typing this at
+the command line:
+
+.. code-block:: bash
+
+ export READTHEDOCS=True # for bash
+ setenv READTHEDOCS True # for csh
+
+This variable is set for automated builds on the free ReadTheDocs service but
+can be used by anyone to force a quick, minimal build.
+
+Now all you need to do is execute sphinx on the yt doc source. Go to the
+documentation directory and build the docs:
+
+.. code-block:: bash
+
+ cd $YT_DEST/src/yt-hg/doc
+ make html
+
+This will produce an html version of the documentation locally in the
+``$YT_DEST/src/yt-hg/doc/build/html`` directory. You can now go there and open
+up ``index.html`` or whatever file you wish in your web browser.
+
+Building the docs (full)
+------------------------
+
+As alluded to earlier, building the full documentation is a bit more involved
+than simply building the static documentation.
+
+The full documentation makes heavy use of custom sphinx extensions to transform
recipes, notebooks, and inline code snippets into python scripts, IPython_
notebooks, or notebook cells that are executed when the docs are built.
@@ -30,12 +81,9 @@
.. _runipy: https://github.com/paulgb/runipy
.. _IPython: http://ipython.org/
-Dependencies
-------------
-
-To build the docs, you will need yt, IPython, runipy, and all supplementary yt
-analysis modules installed. The following dependencies were used to generate the
-yt documentation during the release of yt 2.6 in late 2013.
+To build the full documentation, you will need yt, IPython, runipy, and all
+supplementary yt analysis modules installed. The following dependencies were
+used to generate the yt documentation during the release of yt 2.6 in late 2013.
- Sphinx_ 1.1.3
- IPython_ 1.1
@@ -58,49 +106,32 @@
<http://yt-project.org/data/>`_, including the larger datasets that are not used
in the answer tests.
-Building the docs
------------------
-
-First, you will need to ensure that your testing configuration is properly
+You will need to ensure that your testing configuration is properly
configured and that all of the yt test data is in the testing directory. See
:ref:`run_answer_testing` for more details on how to set up the testing
configuration.
-Next, clone the yt-doc repository, navigate to the root of the repository, and
-do :code:`make html`.
+Now that you have everything set up properly, go to the documentation directory
+and build it using sphinx:
.. code-block:: bash
- hg clone https://bitbucket.org/yt_analysis/yt-doc ./yt-doc
- cd yt-doc
+ cd $YT_DEST/src/yt-hg/doc
make html
If all of the dependencies are installed and all of the test data is in the
-testing directory, this should churn away for a while and eventually generate a
-docs build. This process is lengthy but shouldn't last more than an hour. We
-suggest setting :code:`suppressStreamLogging = True` in your yt configuration
-(See :ref:`configuration-file`) to suppress large amounts of debug output from
+testing directory, this should churn away for a while (~ 1 hour) and
+eventually generate a docs build. We suggest setting
+:code:`suppressStreamLogging = True` in your yt configuration (See
+:ref:`configuration-file`) to suppress large amounts of debug output from
yt.
To clean the docs build, use :code:`make clean`. By default, :code:`make clean`
will not delete the autogenerated API docs, so use :code:`make fullclean` to
delete those as well.
-
-Quick docs builds
------------------
-
-Clearly, building the complete docs is something of an undertaking. If you are
-adding new static content building the complete docs build is probably
-overkill. To skip some of the lengthier operations, you can do the following
-from the bash prompt:
-
-.. code-block:: bash
-
- export READTHEDOCS=True
-
-This variable is set for automated builds on the free ReadTheDocs service but
-can be used by anyone to force a quick, minimal build.
+Building the docs (hybrid)
+--------------------------
It's also possible to create a custom sphinx build that builds a restricted set
of notebooks or scripts. This can be accomplished by editing the Sphinx
diff -r 7562cc292b716c0f95050c365291c090501e91f2 -r a14a150c7c81850df81346162bdaff271e77eb50 doc/source/developing/developing.rst
--- a/doc/source/developing/developing.rst
+++ b/doc/source/developing/developing.rst
@@ -211,16 +211,22 @@
#. Update your pull request by visiting
https://bitbucket.org/YourUsername/yt/pull-request/new
+.. _writing_documentation:
+
How to Write Documentation
++++++++++++++++++++++++++
The process for writing documentation is identical to the above, except that
-instead of ``yt_analysis/yt`` you should be forking and pushing to
-``yt_analysis/yt-doc``. All the source for the documentation is written in
+you're modifying source files in the doc directory (i.e. ``$YT_DEST/src/yt-hg/doc``)
+instead of the src directory (i.e. ``$YT_DEST/src/yt-hg/yt``) of the yt repository.
+All the source for the documentation is written in
`Sphinx <http://sphinx-doc.org/>`_, which uses ReST for markup.
Cookbook recipes go in ``source/cookbook/`` and must be added to one of the
-``.rst`` files in that directory.
+``.rst`` files in that directory.
+
+For more information on how to build the documentation to make sure it looks
+the way you expect it to after modifying it, see :ref:`docs_build`.
How To Get The Source Code For Editing
--------------------------------------
diff -r 7562cc292b716c0f95050c365291c090501e91f2 -r a14a150c7c81850df81346162bdaff271e77eb50 doc/source/developing/intro.rst
--- a/doc/source/developing/intro.rst
+++ b/doc/source/developing/intro.rst
@@ -66,10 +66,8 @@
typo or grammatical fixes, adding a FAQ, or increasing coverage of
functionality, it would be very helpful if you wanted to help out.
-The easiest way to help out is to fork the repository:
-
-http://hg.yt-project.org/yt-doc/fork
-
+The easiest way to help out is to fork the main yt repository (where
+the documentation lives in the ``$YT_DEST/src/yt-hg/doc`` directory,
and then make your changes in your own fork. When you are done, issue a pull
request through the website for your new fork, and we can comment back and
forth and eventually accept your changes.
Repository URL: https://bitbucket.org/yt_analysis/yt/
--
This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.
More information about the yt-svn
mailing list