From d11567200c4f7e66d0a1a056cc90a6bbc22d643d Mon Sep 17 00:00:00 2001 From: William Jamieson Date: Wed, 15 Jun 2022 16:05:49 -0400 Subject: [PATCH 1/7] Update contributing guide --- CONTRIBUTING.md | 17 ----------------- CONTRIBUTING.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 10 +--------- 3 files changed, 50 insertions(+), 26 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 5c404d572..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,17 +0,0 @@ -Please open a new issue or new pull request for 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! - -The main development work is done on the "master" branch. The "stable" branch is -protected and used for official releases. 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. - -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. - -Feedback and feature requests? Is there something missing you would like to see? -Please open an issue or send an email to the maintainers. This package follows -the asdf-format [Code of Conduct](CODE_OF_CONDUCT.md) and strives to provide a -welcoming community to all of our users and contributors. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..4c7669606 --- /dev/null +++ b/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 [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 + `_. + +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 `_. +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 `__ + 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. diff --git a/docs/index.rst b/docs/index.rst index 092dbe4d4..88a12a358 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -72,15 +72,7 @@ parts of ASDF interact and which modules do what and how. Contributing and reporting issues ================================= -We welcome feedback and contributions of all kinds. Contributions of code, -documentation, or general feedback are all appreciated. - -Feature requests and bug reports for the Python implementation can be posted at -`asdf's github page `_. - -The ASDF Standard itself also has a repository on github. Suggestions for -improvements to the ASDF Standard can be reported `here -`_. +.. include:: ../CONTRIBUTING.rst See also ======== From c3e1b153b89d27488e4a5469305b78334f4e7eaf Mon Sep 17 00:00:00 2001 From: William Jamieson Date: Wed, 15 Jun 2022 16:12:58 -0400 Subject: [PATCH 2/7] Move contributing to a new page --- docs/asdf/contributing.rst | 8 ++++++++ docs/index.rst | 17 +++++++---------- 2 files changed, 15 insertions(+), 10 deletions(-) create mode 100644 docs/asdf/contributing.rst diff --git a/docs/asdf/contributing.rst b/docs/asdf/contributing.rst new file mode 100644 index 000000000..00de2120c --- /dev/null +++ b/docs/asdf/contributing.rst @@ -0,0 +1,8 @@ +.. currentmodule:: asdf + +.. _contributing: + +Contributing and reporting issues +================================= + +.. include:: ../../CONTRIBUTING.rst diff --git a/docs/index.rst b/docs/index.rst index 88a12a358..812a2480f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -69,10 +69,14 @@ parts of ASDF interact and which modules do what and how. asdf/developer_overview asdf/developer_versioning -Contributing and reporting issues -================================= +Developer Resources +=================== -.. include:: ../CONTRIBUTING.rst +.. toctree:: + :maxdepth: 1 + + asdf/contributing + asdf/changes See also ======== @@ -82,13 +86,6 @@ See also - `asdf` Python package distribution on `pypi `_ -Changes -======= -.. toctree:: - :maxdepth: 2 - - asdf/changes - Index ===== From ed2dfa399f15e5e51f191d4f77af973203fdd9ea Mon Sep 17 00:00:00 2001 From: William Jamieson Date: Wed, 15 Jun 2022 16:28:10 -0400 Subject: [PATCH 3/7] Update code of conduct --- CODE_OF_CONDUCT.md => CODE_OF_CONDUCT.rst | 11 ++++++----- CONTRIBUTING.rst | 2 +- docs/asdf/code_of_conduct.rst | 5 +++++ docs/index.rst | 1 + 4 files changed, 13 insertions(+), 6 deletions(-) rename CODE_OF_CONDUCT.md => CODE_OF_CONDUCT.rst (90%) create mode 100644 docs/asdf/code_of_conduct.rst diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.rst similarity index 90% rename from CODE_OF_CONDUCT.md rename to CODE_OF_CONDUCT.rst index 37d7b6876..cf34256d1 100644 --- a/CODE_OF_CONDUCT.md +++ b/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 `__ +and `Numfocus `__ codes of conduct. -http://www.astropy.org/code_of_conduct.html -https://www.numfocus.org/about/code-of-conduct/ diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 4c7669606..26630ad14 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,6 +1,6 @@ We welcome feedback and contributions of all kinds. Contributions of code, documentation, or general feedback are all appreciated. This package follows -the asdf-format [Code of Conduct and strives to provide a +the ASDF-format :ref:`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 diff --git a/docs/asdf/code_of_conduct.rst b/docs/asdf/code_of_conduct.rst new file mode 100644 index 000000000..0fd4da177 --- /dev/null +++ b/docs/asdf/code_of_conduct.rst @@ -0,0 +1,5 @@ +.. currentmodule:: asdf + +.. _code-of-conduct: + +.. include:: ../../CODE_OF_CONDUCT.rst diff --git a/docs/index.rst b/docs/index.rst index 812a2480f..7f9ff6220 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -76,6 +76,7 @@ Developer Resources :maxdepth: 1 asdf/contributing + asdf/code_of_conduct asdf/changes See also From de70e7c8063ef1521103ea0cec730dd86605f635 Mon Sep 17 00:00:00 2001 From: William Jamieson Date: Wed, 15 Jun 2022 16:30:26 -0400 Subject: [PATCH 4/7] Update a title --- docs/asdf/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/asdf/contributing.rst b/docs/asdf/contributing.rst index 00de2120c..610b48364 100644 --- a/docs/asdf/contributing.rst +++ b/docs/asdf/contributing.rst @@ -2,7 +2,7 @@ .. _contributing: -Contributing and reporting issues -================================= +Contributing +============ .. include:: ../../CONTRIBUTING.rst From d8f0f330a9edf0db0d70c2d1e55a96f5eee19126 Mon Sep 17 00:00:00 2001 From: William Jamieson Date: Wed, 15 Jun 2022 16:38:27 -0400 Subject: [PATCH 5/7] Add badges to main docs page --- README.rst | 5 +++-- docs/index.rst | 8 ++++++-- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index f855841ad..d80635382 100644 --- a/README.rst +++ b/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 @@ -35,8 +37,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: diff --git a/docs/index.rst b/docs/index.rst index 7f9ff6220..ec091495b 100644 --- a/docs/index.rst +++ b/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,8 +73,8 @@ parts of ASDF interact and which modules do what and how. asdf/developer_overview asdf/developer_versioning -Developer Resources -=================== +Resources +========= .. toctree:: :maxdepth: 1 From 2e534249e2d13f03e3755ed2eee0c8f6b838e348 Mon Sep 17 00:00:00 2001 From: William Jamieson Date: Wed, 15 Jun 2022 16:55:03 -0400 Subject: [PATCH 6/7] Add citation --- CITATION.rst | 25 +++++++++++++++++++++++++ README.rst | 4 ++++ docs/asdf/citation.rst | 9 +++++++++ docs/index.rst | 1 + 4 files changed, 39 insertions(+) create mode 100644 CITATION.rst create mode 100644 docs/asdf/citation.rst diff --git a/CITATION.rst b/CITATION.rst new file mode 100644 index 000000000..e55415250 --- /dev/null +++ b/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.} + } diff --git a/README.rst b/README.rst index d80635382..7d3c7562f 100644 --- a/README.rst +++ b/README.rst @@ -21,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 diff --git a/docs/asdf/citation.rst b/docs/asdf/citation.rst new file mode 100644 index 000000000..72d5e3e51 --- /dev/null +++ b/docs/asdf/citation.rst @@ -0,0 +1,9 @@ +.. currentmodule:: asdf + +.. _citation: + +******** +Citation +******** + +.. include:: ../../CITATION.rst diff --git a/docs/index.rst b/docs/index.rst index ec091495b..5a30180de 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -82,6 +82,7 @@ Resources asdf/contributing asdf/code_of_conduct asdf/changes + asdf/citation See also ======== From 9d8e7d65aabe5ff28bc8fbb2b7a22cb5d18795b9 Mon Sep 17 00:00:00 2001 From: William Jamieson Date: Wed, 15 Jun 2022 16:56:59 -0400 Subject: [PATCH 7/7] Update changes --- CHANGES.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index 6ccbcea4b..46e41a98c 100644 --- a/CHANGES.rst +++ b/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)