[Yt-svn] yt-commit r1736 - trunk/doc
mturk at wrangler.dreamhost.com
mturk at wrangler.dreamhost.com
Tue Jun 1 09:55:15 PDT 2010
Author: mturk
Date: Tue Jun 1 09:55:13 2010
New Revision: 1736
URL: http://yt.enzotools.org/changeset/1736
Log:
Adding initial import of coding standards and docstring examples and idioms.
Added:
trunk/doc/coding_styleguide.txt
trunk/doc/docstring_example.txt
trunk/doc/docstring_idioms.txt
Added: trunk/doc/coding_styleguide.txt
==============================================================================
--- (empty file)
+++ trunk/doc/coding_styleguide.txt Tue Jun 1 09:55:13 2010
@@ -0,0 +1,37 @@
+Style Guide for Coding in yt
+============================
+
+ * In general, follow PEP-8 guidelines.
+ * Classes are ConjoinedCapitals, methods and functions are
+ lowercase_with_underscores.
+ * Use 4 spaces, not tabs, to represent indentation.
+ * Avoid at all costs importing "*" from a function or a module unless that
+ module is "yt.funcs" or "yt.arraytypes". "yt.mods" may be a special case,
+ but if at all possible avoid importing it.
+ * Numpy is to be imported as "na" not "np". While this may change in the
+ future, for now this is the correct idiom.
+ * Do not use too many keyword arguments. If you have a lot of keyword
+ arguments, then you are doing too much in __init__ and not enough via
+ parameter setting.
+ * Line widths should not be more than 80 characters.
+ * Do not use unecessary parenthesis in conditionals. if((something) and
+ (something_else)) should be rewritten as if something and something_else.
+ Python is more forgiving than C.
+ * In function arguments, place spaces before commas. def something(a,b,c)
+ should be def something(a, b, c).
+ * Do not use nested classes unless you have a very good reason to, such as
+ requiring a namespace or class-definition modification. Classes should live
+ at the top level. __metaclass__ is exempt from this.
+ * Don't create a new class to replicate the functionality of an old class --
+ replace the old class. Too many options makes for a confusing user
+ experience.
+ * Parameter files are a last resort.
+ * Avoid copying memory when possible. For example, don't do
+ "a = a.reshape(3,4)" when "a.shape = (3,4)" will do, and "a = a * 3" should
+ be "na.multiply(a, 3, a)".
+ * The usage of the **kwargs construction should be avoided. If they cannoted
+ be avoided, they must be explained, even if they are only to be passed on to
+ a nested function.
+ * Doc strings should describe input, output, behavior, and any state changes
+ that occur on an object. See the file `doc/docstring_example.txt` for a
+ fiducial example of a docstring.
Added: trunk/doc/docstring_example.txt
==============================================================================
--- (empty file)
+++ trunk/doc/docstring_example.txt Tue Jun 1 09:55:13 2010
@@ -0,0 +1,86 @@
+ r"""A one-line summary that does not use variable names or the
+ function name.
+
+ Several sentences providing an extended description. Refer to
+ variables using back-ticks, e.g. `var`.
+
+ Parameters
+ ----------
+ var1 : array_like
+ Array_like means all those objects -- lists, nested lists, etc. --
+ that can be converted to an array. We can also refer to
+ variables like `var1`.
+ var2 : int
+ The type above can either refer to an actual Python type
+ (e.g. ``int``), or describe the type of the variable in more
+ detail, e.g. ``(N,) ndarray`` or ``array_like``.
+ Long_variable_name : {'hi', 'ho'}, optional
+ Choices in brackets, default first when optional.
+
+ Returns
+ -------
+ describe : type
+ Explanation
+ output : type
+ Explanation
+ tuple : type
+ Explanation
+ items : type
+ even more explaining
+
+ Other Parameters
+ ----------------
+ only_seldom_used_keywords : type
+ Explanation
+ common_parameters_listed_above : type
+ Explanation
+
+ Raises
+ ------
+ BadException
+ Because you shouldn't have done that.
+
+ See Also
+ --------
+ otherfunc : relationship (optional)
+ newfunc : Relationship (optional), which could be fairly long, in which
+ case the line wraps here.
+ thirdfunc, fourthfunc, fifthfunc
+
+ Notes
+ -----
+ Notes about the implementation algorithm (if needed).
+
+ This can have multiple paragraphs.
+
+ You may include some math:
+
+ .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
+
+ And even use a greek symbol like :math:`omega` inline.
+
+ References
+ ----------
+ Cite the relevant literature, e.g. [1]_. You may also cite these
+ references in the notes section above.
+
+ .. [1] O. McNoleg, "The integration of GIS, remote sensing,
+ expert systems and adaptive co-kriging for environmental habitat
+ modelling of the Highland Haggis using object-oriented, fuzzy-logic
+ and neural-network techniques," Computers & Geosciences, vol. 22,
+ pp. 585-588, 1996.
+
+ Examples
+ --------
+ These are written in doctest format, and should illustrate how to
+ use the function. Use the variables 'pf' for the parameter file, 'pc' for
+ a plot collection, 'c' for a center, and 'L' for a vector.
+
+ >>> a=[1,2,3]
+ >>> print [x + 3 for x in a]
+ [4, 5, 6]
+ >>> print "a\n\nb"
+ a
+ b
+
+ """
Added: trunk/doc/docstring_idioms.txt
==============================================================================
--- (empty file)
+++ trunk/doc/docstring_idioms.txt Tue Jun 1 09:55:13 2010
@@ -0,0 +1,54 @@
+Idioms for Docstrings in yt
+===========================
+
+For a full list of recognized constructs for marking up docstrings, see the
+Sphinx documentation:
+
+http://sphinx.pocoo.org/
+
+Specifically, this section:
+
+http://sphinx.pocoo.org/markup/index.html
+http://sphinx.pocoo.org/markup/inline.html#cross-referencing-python-objects
+
+Variables in Examples
+---------------------
+
+In order to construct short, useful examples, some variables must be specified.
+However, because often examples require a bit of setup, here is a list of
+useful variable names that correspond to specific instances that the user is
+presupposed to have created.
+
+ * `pf`: a parameter file, loaded successfully
+ * `sp`: a sphere
+ * `c`: a 3-component "center"
+ * `L`: a 3-component vector that corresponds to either angular momentum or a
+ normal vector
+
+Cross-Referencing
+-----------------
+
+To enable sufficient linkages between different sections of the documentation,
+good cross-referencing is key. To reference a section of the documentation,
+you can use this construction:
+
+ For more information, see :ref:`image_writer`.
+
+This will insert a link to the section in the documentation which has been
+identified with `image_writer` as its name.
+
+Referencing Classes and Functions
+---------------------------------
+
+To indicate the return type of a given object, you can reference it using this
+construction:
+
+ This function returns a :class:`PlotCollection`.
+
+To reference a function, you can use:
+
+ To write out this array, use :func:`save_image`.
+
+To reference a method, you can use:
+
+ To add a projection, use :meth:`PlotCollection.add_projection`.
More information about the yt-svn
mailing list