Merge pull request #34 from chummels/docs

Updating docs -- Closes #27 and more

doc/source/conf.py

@@ -56,7 +56,7 @@
 
 # General information about the project.
 project = u'Trident'
-copyright = u'2015-2017, Trident Project'
+copyright = u'Trident Project. All rights reserved.'
 author = u'Trident Project'
 
 # The version info for the project you're documenting, acts as replacement for

doc/source/faq.rst

@@ -5,6 +5,35 @@ Frequently Asked Questions
 
 .. _what-version-am-i-running:
 
+Why don't I have any absorption features in my spectrum?
+--------------------------------------------------------
+
+There are many reasons you might not have any absorption features in your
+spectrum, but we'll cover a few of the basic explanations here.  
+
+ #. Your absorbers are in a different part of the spectrum than you're plotting.
+    Make sure you are plotting the wavelength range where you expect to see the 
+    absorption by taking into account the wavelength of your absorption features
+    coupled with the redshift of your dataset: :math:`\lambda_{obs} = (1 + z) \lambda_{rest}`
+    To see the wavelength of specific ionic transitions, see the line list in:
+    ``/trident/trident/data/line_lists/lines.txt``.
+
+ #. Your sightlines do not have sufficient column densities of the desired
+    ions to actually make an absorption feature.  Look at the total column
+    density of your desired ions in your sightline by multiplying the
+    density times the path length and summing it all up.  Here is an 
+    example for showing the total O VI column density in a ray::
+
+        import trident
+        <generate/load your ray object>
+        trident.add_ion_fields(ray, ['O VI'])
+        ad = ray.all_data()
+        print((ad[('gas', 'O_p5_number_density')] * ad[('gas', 'dl')]).sum())
+
+    Depending on the ion, you usually need to see at least :math:`10^{12} cm^{-2}`
+    to have any appreciable absorption.  Try sending a sightline through a
+    denser region in your simulation that might have more of that ion.
+
 What version of Trident am I running?
 -------------------------------------
 
@@ -62,3 +91,8 @@ How do I cite Trident in my research?
 -------------------------------------
 
 Check out our :ref:`citation <citation>` page.
+
+How do I get an invite to the Trident slack channel?
+----------------------------------------------------
+
+Click on this `link <https://join.slack.com/t/trident-project/shared_invite/enQtMzE4ODM5NTg1Nzk0LTA2OTBmMGZmZTVmY2JhMmYwNjMwMjdhZWEyZGQ1YzNiY2EzOGY2MzVhNDY3YzMwZWI5YTY3NmU5YWQ4NjU5YTQ>`_.

doc/source/help.rst

@@ -37,6 +37,13 @@ include details like the operating system you're using, the type of dataset
 you're trying to reduce, the version of Trident and yt you're using (find it
 out :ref:`here <what-version-am-i-running>`), and of course, a description of 
 the problem you're having with any relevant traceback errors.  
-Our mailing list is located here:
+Our mailing list is located here::
 
 https://groups.google.com/forum/#!forum/trident-project-users 
+
+Join our Slack Channel
+----------------------
+
+We have a slack channel for help and discussions amongst the users and
+developers of Trident.  You can generate an invite for yourself by clicking
+on this `link <https://join.slack.com/t/trident-project/shared_invite/enQtMzE4ODM5NTg1Nzk0LTA2OTBmMGZmZTVmY2JhMmYwNjMwMjdhZWEyZGQ1YzNiY2EzOGY2MzVhNDY3YzMwZWI5YTY3NmU5YWQ4NjU5YTQ>`_ and following the instructions.

doc/source/installation.rst

@@ -17,25 +17,21 @@ Currently, there are three versions of Trident: the `stable version
 The stable version is tried and tested, and it normally operates on a stable
 version of yt.  The development version is actively being updated with new
 features, and it is also tied to the development version of yt, so occasionally
-unforseen bugs can crop up as these new features are added.
-The demeshening version is a variant of Trident for treating particle-based
-datasets more natively.  For more information about the demeshening and full
-installation instructions, please see our `demeshening notebook
-<https://nbviewer.jupyter.org/url/trident-project.org/notebooks/trident_demesh_install.ipynb>`_.
+unforseen bugs can crop up as these new features are added.  The demeshening
+version is currently in beta and active development and is used for better
+results on particle-based datasets.
 The installation steps are slightly different between the three versions,
 so pay attention in the steps below.  Don't worry if you want to change later,
 you can always switch between the two versions easily enough by following the
 directions in :ref:`uninstallation`.
 
-.. warning::
-
-    The current stable version of yt, yt 3.4.0, has a 
-    `bug <https://github.com/yt-project/yt/issues/1610>`_ affecting the 
-    temperature field in cosmological SPH datasets at z>0. We currently 
-    recommend using the development version of yt, where this bug is fixed, 
-    for use with trident (both stable and dev) until this bugfix makes it 
-    into yt stable. The directions below will result in the yt development 
-    branch being installed.
+.. note::
+    The demeshening version is a variant of Trident for treating particle-based
+    datasets more natively.  The demeshening version will give faster and more 
+    accurate results with less memory overhead for particle-based datasets.  
+    For more information about the demeshening and full installation 
+    instructions, please see our `demeshening notebook
+    <https://nbviewer.jupyter.org/url/trident-project.org/notebooks/trident_demesh_install.ipynb>`_.
 
 .. _step-1:
 

doc/source/testing.rst

@@ -142,8 +142,8 @@ yt and trident that give the desired behavior).  Tag the Trident changeset with
 the next gold standard iteration.  You can see the current iteration by looking
 in the ``.travis.yml`` file at the ``TRIDENT_GOLD`` entry--enumerate this and
 tag the changeset.  Update the ``.travis.yml`` file so that the ``YT_GOLD`` and
-``TRIDENT_GOLD`` entries point to your desired changeset and tag.  Finally,
-you have to explicitly push the new tag (hereafter ``test-standard-v2``) to 
+``TRIDENT_GOLD`` entries point to your desired changeset and tag.  You have to 
+explicitly push the new tag (hereafter ``test-standard-v2``) to 
 the repository.
 
 .. code-block:: bash
@@ -155,3 +155,7 @@ the repository.
    $ git commit
    $ git push origin
    $ git push origin test-standard-v2
+
+Lastly, someone with admin access to the main trident repository will have to 
+clear Travis' cache, so that it regenerates new answer test results.  This can 
+be done manually here: https://travis-ci.org/trident-project/trident/caches .