Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix formatting ofr README.rst #175

Merged
merged 3 commits into from
May 17, 2024
Merged

Fix formatting ofr README.rst #175

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5791590
Fix formatting for README.rst
hamogu May 12, 2024
0ce09d0
Formatting of Readme on GH
hamogu May 13, 2024
339cd27
Fix link typo
jagerber48 May 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 50 additions & 46 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,29 @@
.. image:: https://www.repostatus.org/badges/latest/wip.svg
.. container::

|Repo Status| |pyOpenSci| |Documentation Status| |PyPI Version| |PyPI Python| |Coverage Status| |GH Workflow Status| |Zenodo|

.. |Repo Status| image:: https://www.repostatus.org/badges/latest/wip.svg
:target: https://www.repostatus.org/#wip
:alt: Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.
.. image:: https://tinyurl.com/y22nb8up
.. |pyOpenSci| image:: https://tinyurl.com/y22nb8up
:target: https://github.com/pyOpenSci/software-review/issues/121
:alt: pyOpenSci
.. image:: https://img.shields.io/readthedocs/sciform?logo=readthedocs&link=https%3A%2F%2Fsciform.readthedocs.io%2Fen%2Fstable%2F
.. |Documentation Status| image:: https://img.shields.io/readthedocs/sciform?logo=readthedocs&link=https%3A%2F%2Fsciform.readthedocs.io%2Fen%2Fstable%2F
:target: https://sciform.readthedocs.io/en/stable/
:alt: Read the Docs
.. image:: https://img.shields.io/pypi/v/sciform?logo=pypi
.. |PyPI Version| image:: https://img.shields.io/pypi/v/sciform?logo=pypi
:target: https://pypi.org/project/sciform/
:alt: PyPI - Version
.. image:: https://img.shields.io/pypi/pyversions/sciform?logo=python
.. |PyPI Python| image:: https://img.shields.io/pypi/pyversions/sciform?logo=python
:target: https://pypi.org/project/sciform/
:alt: PyPI - Python Version
.. image:: https://img.shields.io/codecov/c/github/jagerber48/sciform?logo=codecov
.. |Coverage Status| image:: https://img.shields.io/codecov/c/github/jagerber48/sciform?logo=codecov
:target: https://codecov.io/gh/jagerber48/sciform
:alt: Codecov
.. image:: https://img.shields.io/github/actions/workflow/status/jagerber48/sciform/python-package.yml?logo=github%20actions
.. |GH Workflow Status| image:: https://img.shields.io/github/actions/workflow/status/jagerber48/sciform/python-package.yml?logo=github%20actions
:target: https://github.com/jagerber48/sciform/blob/main/.github/workflows/python-package.yml
:alt: GitHub Workflow Status
.. image:: https://zenodo.org/badge/645611310.svg
.. |Zenodo| image:: https://zenodo.org/badge/645611310.svg
:target: https://zenodo.org/doi/10.5281/zenodo.10645272
:alt: Zenodo

Expand All @@ -28,9 +32,9 @@
sciform
#######

| **Repository:** `<https://github.com/jagerber48/sciform>`_
| **Documentation:** `<https://sciform.readthedocs.io/en/stable/>`_
| **PyPi:** `<https://pypi.org/project/sciform/>`_
| **Repository:** `<https://github.com/jagerber48/sciform>`_
| **Documentation:** `<https://sciform.readthedocs.io/en/stable/>`_
| **PyPi:** `<https://pypi.org/project/sciform/>`_

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please have a blank line appear in the rendered output between the PyPi line and the "We would greatly appreciate..." line?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wish I could, but it seems that GH does not render it the way I think it should. I tried an extra | attached or in it's own block, I tried empty lines, etc but GH does not render either. I also don't want to get too complicated just just a blank line in a readme. I think it looks better already and I can't find an easy solution to add a blank line. I suggest to leave as is and live with it - perfect is the enemy of good - and rather put our time into more important things.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah ok, No problem then. Didn't realize GH is doing something to make it challenging to include a blank line! Ok, I'll look over everything more carefully when I get a chance!

We would greatly appreciate you taking the time to fill out the
`User Experience Survey <https://forms.gle/TkkKgywYyEMKu9U37>`_ to help
Expand Down Expand Up @@ -77,55 +81,55 @@ For many more details see

``sciform`` provides a wide variety of formatting options which can be
controlled when constructing ``Formatter`` objects which are then used
to format numbers into strings according to the selected options.

>>> from sciform import Formatter
>>> formatter = Formatter(
... round_mode="dec_place", ndigits=6, upper_separator=" ", lower_separator=" "
... )
>>> print(formatter(51413.14159265359))
51 413.141 593
>>> formatter = Formatter(round_mode="sig_fig", ndigits=4, exp_mode="engineering")
>>> print(formatter(123456.78))
123.5e+03
to format numbers into strings according to the selected options::

>>> from sciform import Formatter
>>> formatter = Formatter(
... round_mode="dec_place", ndigits=6, upper_separator=" ", lower_separator=" "
... )
>>> print(formatter(51413.14159265359))
51 413.141 593
>>> formatter = Formatter(round_mode="sig_fig", ndigits=4, exp_mode="engineering")
>>> print(formatter(123456.78))
123.5e+03

Users can also format numbers by constructing ``SciNum`` objects and
using string formatting to format the ``SciNum`` instances according
to a custom FSML.
to a custom FSML::

>>> from sciform import SciNum
>>> num = SciNum(12345)
>>> print(f"{num:!2f}")
12000
>>> print(f"{num:!2r}")
12e+03
>>> from sciform import SciNum
>>> num = SciNum(12345)
>>> print(f"{num:!2f}")
12000
>>> print(f"{num:!2r}")
12e+03

In addition to formatting individual numbers, ``sciform`` can be used
to format pairs of numbers as value/uncertainty pairs.
This can be done by passing two numbers into a ``Formatter`` call or by
using the ``SciNum`` object.
using the ``SciNum`` object::

>>> formatter = Formatter(ndigits=2, upper_separator=" ", lower_separator=" ")
>>> print(formatter(123456.654321, 0.00345))
123 456.654 3 ± 0.003 4
>>> formatter = Formatter(ndigits=4, exp_mode="engineering")
>>> print(formatter(123456.654321, 0.00345))
(123.456654321 ± 0.000003450)e+03
>>> formatter = Formatter(ndigits=2, upper_separator=" ", lower_separator=" ")
>>> print(formatter(123456.654321, 0.00345))
123 456.654 3 ± 0.003 4
>>> formatter = Formatter(ndigits=4, exp_mode="engineering")
>>> print(formatter(123456.654321, 0.00345))
(123.456654321 ± 0.000003450)e+03

>>> num = SciNum(123456.654321, 0.00345)
>>> print(f"{num:!2f}")
123456.6543 ± 0.0034
>>> print(f"{num:!2f()}")
123456.6543(34)
>>> num = SciNum(123456.654321, 0.00345)
>>> print(f"{num:!2f}")
123456.6543 ± 0.0034
>>> print(f"{num:!2f()}")
123456.6543(34)

Note that the above examples demonstrate that ``sciform`` uses
`"round-to-even" <https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even>`_
rounding.
rounding::

>>> print(f"{SciNum(865):!2}")
860
>>> print(f"{SciNum(875):!2}")
880
>>> print(f"{SciNum(865):!2}")
860
>>> print(f"{SciNum(875):!2}")
880

See `Formatting Options <https://sciform.readthedocs.io/en/stable/options.html>`_,
`Format Specification Mini-Language <https://sciform.readthedocs.io/en/stable/fsml.html>`_
Expand Down