Update docs to include citation and contributing guides

CHANGES.rst

@@ -3,7 +3,7 @@
 
 The ASDF Standard is at v1.6.0
 
-- Overhaul of the ASDF documentation to make it more consistent and readable. [#1142]
+- Overhaul of the ASDF documentation to make it more consistent and readable. [#1142, #1152]
 - Update deprecated instances of `abstractproperty` to `abstractmethod` [#1148]
 
 2.12.0 (2022-06-06)

CITATION.rst

@@ -0,0 +1,25 @@
+If you use ASDF for work/research presented in a publication (whether directly,
+as a dependency to another package), please cite the Zenodo DOI for the appropriate
+version of ASDF.  The versions (and their BibTeX entries) can be found at:
+
+.. include:: ../../README.rst
+    :start-after: begin-zenodo:
+    :end-before: end-zenodo:
+
+We also recommend and encourage you to cite the general ASDF paper:
+
+.. code:: bibtex
+
+    @article{GREENFIELD2015240,
+    title = {ASDF: A new data format for astronomy},
+    journal = {Astronomy and Computing},
+    volume = {12},
+    pages = {240-251},
+    year = {2015},
+    issn = {2213-1337},
+    doi = {https://doi.org/10.1016/j.ascom.2015.06.004},
+    url = {https://www.sciencedirect.com/science/article/pii/S2213133715000645},
+    author = {P. Greenfield and M. Droettboom and E. Bray},
+    keywords = {FITS, File formats, Standards, World coordinate system},
+    abstract = {We present the case for developing a successor format for the immensely successful FITS format. We first review existing alternative formats and discuss why we do not believe they provide an adequate solution. The proposed format is called the Advanced Scientific Data Format (ASDF) and is based on an existing text format, YAML, that we believe removes most of the current problems with the FITS format. An overview of the capabilities of the new format is given along with specific examples. This format has the advantage that it does not limit the size of attribute names (akin to FITS keyword names) nor place restrictions on the size or type of values attributes have. Hierarchical relationships are explicit in the syntax and require no special conventions. Finally, it is capable of storing binary data within the file in its binary form. At its basic level, the format proposed has much greater applicability than for just astronomical data.}
+    }

CODE_OF_CONDUCT.md → CODE_OF_CONDUCT.rst

@@ -1,6 +1,7 @@
-# asdf-format Open Source Code of Conduct
+ASDF-format Open Source Code of Conduct
+---------------------------------------
 
-We expect all "asdf-format" organization projects to adopt a code of conduct
+We expect all "ASDF-format" organization projects to adopt a code of conduct
 that ensures a productive, respectful environment for all open source
 contributors and participants. We are committed to providing a strong and
 enforced code of conduct and expect everyone in our community to follow these
@@ -53,7 +54,7 @@ This code of conduct applies to all community situations online and offline,
 including mailing lists, forums, social media, conferences, meetings, associated
 social events, and one-to-one interactions.
 
-Parts of this code of conduct have been adapted from the Astropy and Numfocus
+Parts of this code of conduct have been adapted from the
+`Astropy <http://www.astropy.org/code_of_conduct.html>`__
+and `Numfocus <https://www.numfocus.org/about/code-of-conduct/>`__
 codes of conduct.
-http://www.astropy.org/code_of_conduct.html
-https://www.numfocus.org/about/code-of-conduct/

CONTRIBUTING.rst

@@ -0,0 +1,49 @@
+We welcome feedback and contributions of all kinds. Contributions of code,
+documentation, or general feedback are all appreciated. This package follows
+the ASDF-format :ref:`Code Of Conduct <code-of-conduct>` and strives to provide a
+welcoming community to all of our users and contributors.
+
+New to GitHub or open source projects? If you are unsure about where to start or
+haven't used GitHub before, please feel free to contact the package maintainers.
+
+.. note::
+    The ASDF Standard itself also has a repository on github. Suggestions for
+    improvements to the ASDF Standard can be reported `here
+    <https://github.com/asdf-format/asdf-standard>`_.
+
+Feedback, Feature Requests, and Bug Reports
+-------------------------------------------
+
+Feedback, feature requests, and bug reports for the ASDF Python implementation
+can be posted via `ASDF's github page <https://github.com/asdf-format/asdf>`_.
+Please open a new issue any questions, bugs, feedback, or new features you would
+like to see. If there is an issue you would like to work on, please leave a comment
+and we will be happy to assist. New contributions and contributors are very welcome!
+
+Contributing Code and Bug Fixes
+-------------------------------
+
+To contribute code to ASDF please fork ASDF first and then open a pull request
+from your fork to ASDF. Typically, the main development work is done on the
+"master" branch.  The rest of the branches are for release maintenance and should
+not be used normally. Unless otherwise told by a maintainer, pull request should
+be made and submitted to the "master" branch.
+
+.. note::
+    The "stable" branch is protected and used for official releases.
+
+We ask that all contributions include unit tests to verify that the code works as
+intended. These tests are run automatically by GitHub when pull requests are open.
+If you have difficulties with tests failing or writing new tests please reach out
+to the maintainers, who are glad to assist you.
+
+.. note::
+    ASDF uses both ``black`` and ``isort`` to format your code, so we ask that
+    you run these tools regularly on your code to ensure that it is formatted
+    correctly.
+
+    To make this easier, we have included `pre-commit <https://pre-commit.com/>`__
+    support for ASDF. We suggest that you install ``pre-commit``, so that your
+    code is automatically formatted before you commit. For those who do not run
+    these tools regularly, the ``pre-commit-ci`` bot will attempt to fix the issues
+    with your pull request when you submit it.

README.rst

@@ -1,6 +1,8 @@
 ASDF - Advanced Scientific Data Format
 ======================================
 
+.. _begin-badges:
+
 .. image:: https://github.com/asdf-format/asdf/workflows/CI/badge.svg
     :target: https://github.com/asdf-format/asdf/actions
     :alt: CI Status
@@ -19,9 +21,13 @@ ASDF - Advanced Scientific Data Format
 .. image:: https://codecov.io/gh/asdf-format/asdf/branch/master/graphs/badge.svg
     :target: https://codecov.io/gh/asdf-format/asdf
 
+.. _begin-zenodo:
+
 .. image:: https://zenodo.org/badge/18112754.svg
     :target: https://zenodo.org/badge/latestdoi/18112754
 
+.. _end-zenodo:
+
 .. image:: https://img.shields.io/pypi/l/asdf.svg
     :target: https://img.shields.io/pypi/l/asdf.svg
 
@@ -35,8 +41,7 @@ ASDF - Advanced Scientific Data Format
 .. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
     :target: https://pycqa.github.io/isort/
 
-
-|
+.. _end-badges:
 
 .. _begin-summary-text:
 

docs/asdf/citation.rst

@@ -0,0 +1,9 @@
+.. currentmodule:: asdf
+
+.. _citation:
+
+********
+Citation
+********
+
+.. include:: ../../CITATION.rst

docs/asdf/code_of_conduct.rst

@@ -0,0 +1,5 @@
+.. currentmodule:: asdf
+
+.. _code-of-conduct:
+
+.. include:: ../../CODE_OF_CONDUCT.rst

docs/asdf/contributing.rst

@@ -0,0 +1,8 @@
+.. currentmodule:: asdf
+
+.. _contributing:
+
+Contributing
+============
+
+.. include:: ../../CONTRIBUTING.rst

docs/index.rst

@@ -4,6 +4,10 @@
 ASDF - Advanced Scientific Data Format
 **************************************
 
+.. include:: ../README.rst
+    :start-after: begin-badges:
+    :end-before: end-badges:
+
 `asdf` is a tool for reading and writing Advanced Scientific Data
 Format (ASDF) files.
 
@@ -69,18 +73,16 @@ parts of ASDF interact and which modules do what and how.
   asdf/developer_overview
   asdf/developer_versioning
 
-Contributing and reporting issues
-=================================
-
-We welcome feedback and contributions of all kinds. Contributions of code,
-documentation, or general feedback are all appreciated.
+Resources
+=========
 
-Feature requests and bug reports for the Python implementation can be posted at
-`asdf's github page <https://github.com/asdf-format/asdf>`_.
+.. toctree::
+  :maxdepth: 1
 
-The ASDF Standard itself also has a repository on github. Suggestions for
-improvements to the ASDF Standard can be reported `here
-<https://github.com/asdf-format/asdf-standard>`_.
+  asdf/contributing
+  asdf/code_of_conduct
+  asdf/changes
+  asdf/citation
 
 See also
 ========
@@ -90,13 +92,6 @@ See also
 
 - `asdf` Python package distribution on `pypi <https://pypi.org/project/asdf/>`_
 
-Changes
-=======
-.. toctree::
-  :maxdepth: 2
-
-  asdf/changes
-
 Index
 =====