documentation building, readthedocs config #203

newville · 2024-03-15T01:49:50Z

this is a work-in-progress to start on getting docs to build and push to readthedocs.

so far, it has not touched the doc contents, but some of that will need changing as well.

codecov · 2024-03-15T01:51:45Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.74%. Comparing base (ea1d664) to head (b1ae532).
Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #203      +/-   ##
==========================================
+ Coverage   95.59%   95.74%   +0.15%     
==========================================
  Files          12       12              
  Lines        1905     1905              
==========================================
+ Hits         1821     1824       +3     
+ Misses         84       81       -3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

newville · 2024-04-22T02:37:48Z

This PR to update the docs is now at the state of being incomplete but reviewable.

By way of documentation for what has changed in this PR:

This adds config files for codecov and readthedocs. These might need more tweaking or have been updated already in earlier PRs.
some sphinx changes were needed to the layout.
I made "index" a lot shorter. It is now mostly an intro and Table of Contents. I added a custom "sidebar" giving the version, quick install instructions, and a link to GitHub.
moved most of what was in index.rst to install.rst, but heavily edited this to more modern install instructions, and updated Credits to describe the recent transition to the lmfit github org.
made some edits to "user_guide", but more could be done. No substantial changes to "numpy" or "tech guide".
I updated the docstrings for ufloat and ufloat_fromstr, so that "autodoc" can be (and is) used with sphinx.
for linking to PDF and static zipped HTML, the current approach is fragile, so I sort of set these up differently:

I am fine with using readthedocs. But, I am also willing to use GitHub pages. I use this for almost all my other projects, and it has the distinct advantage of allowing us to put any files we want in the gh-pages branch, including static PDFs.

By way of proof-of-concept and viewing the development here, I added a gh-pages branch to the main lmfit/uncertainties and pushed the rendered results of the current state of this PR there. This is viewable at https://lmfit.github.io/uncertainties/

We could use both, and/or make the links to the PDF and zipped HTML point to the fully-qualified URLs https://lmfit.github.io/uncertainties/uncertainties.pdf and https://lmfit.github.io/uncertainties/uncertainties_doc.zip.

I think there is always more to do. And I would say that all the changes here could be undone or modified: suggestions most welcome.

andrewgsavage · 2024-04-22T22:25:16Z

doc/user_guide.rst


-.. The "import uncertainties" is put here because some examples requires
-   uncertainties to have been imported (and not only ufloat).
+>>> import uncertainties as un


does this conflict with any other packages?

I think it does not but have no idea how to tell!

dunno. One could probably ask that about any abbreviation.

andrewgsavage · 2024-04-22T22:38:33Z

the table of contents has switched position with 'get uncertainties' on index.html

andrewgsavage · 2024-04-22T22:50:24Z

I'd remove the autofuncton then this looks good to merge

newville · 2024-04-23T02:21:34Z

@andrewgsavage

the table of contents has switched position with 'get uncertainties' on index.html

Yes. The intention is that the information on how to get uncertainties is prominent on the index page.
Is this a problem?

I'd remove the autofuncton then this looks good to merge

Do you mean you want to not have the docstrings for ufloat and ufloat_fromstr? One of the (okay, many) things I find odd about the current doc is that these are not provided. And the docstrings are kind of a mess.

I think these autofunctions could be moved, but I think they should be given somewhere.

andrewgsavage · 2024-04-23T07:04:38Z

That's fine, the 'get uncertainties' on the box on the right where the toc would be looks odd I mean to move them to another page. Personally I'd leave that page till a later PR when there's more updated doc strings, but you could do so in this PR.

…

On Tue, 23 Apr 2024, 03:21 Matt Newville, ***@***.***> wrote: @andrewgsavage <https://github.com/andrewgsavage> the table of contents has switched position with 'get uncertainties' on index.html Yes. The intention is that the information on how to get uncertainties is prominent on the index page. Is this a problem? I'd remove the autofuncton then this looks good to merge Do you mean you want to not have the docstrings for ufloat and ufloat_fromstr? One of the (okay, many) things I find odd about the current doc is that these are not provided. And the docstrings are kind of a mess. I think these autofunctions could be moved, but I think they should be given somewhere. — Reply to this email directly, view it on GitHub <#203 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADEMLEGPZRIGT3TBN5DX5B3Y6XAUHAVCNFSM6AAAAABEXEZDVKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANZRGI4DQOBYGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

andrewgsavage · 2024-04-22T22:30:46Z

doc/user_guide.rst


-Each number created this way is an **independent (random) variable**
-(for details, see the :ref:`Technical Guide <math_def_num_uncert>`).
+.. autofunction:: ufloat


The section created from the docstring is quite long, making this page more difficult to read for a new user.

I'd prefer if it linked to the function in an API reference section

That seems OK. The current docs don't describe Variable, UFloat, or AffineScalarFunc. They sort of talk about "value with an uncertainty". I think that an API section really should mention this. Opinions?

andrewgsavage · 2024-04-22T22:50:13Z

doc/user_guide.rst


-.. The "import uncertainties" is put here because some examples requires
-   uncertainties to have been imported (and not only ufloat).
+>>> import uncertainties as un


I think it does not but have no idea how to tell!

andrewgsavage · 2024-04-22T22:53:10Z

doc/install.rst

+used.  Running the test suite requires `pytest` and `pytest_cov`, and building
+these docs requires `sphinx`.  To install these optional packages, use one of:
+
+.. code-block:: sh


This is very helpful, thanks for adding

andrewgsavage · 2024-04-30T21:56:20Z

doc/formatting.rst

+>>> print('Result = {:10.2f}'.format(x))
+Result =       0.20+/-      0.01
+
+(Python 2.6 requires ``'{0:10.2f}'`` instead, with the usual explicit


python2 reference can be deleted

hah! thanks - I missed that one.

andrewgsavage · 2024-04-30T21:57:33Z

doc/formatting.rst

+
+>>> print('Automatic number of digits on the uncertainty: {}'.format(x))
+Automatic number of digits on the uncertainty: 0.200+/-0.010
+>>> print(x0


close bracket

might be worth setting these up as doc tests in the future

andrewgsavage · 2024-04-30T22:11:26Z

doc/user_guide.rst


-.. The "import uncertainties" is put here because some examples requires
-   uncertainties to have been imported (and not only ufloat).
+ >>> import uncertainties


single space before >>>

On second read, I think this (lines 19-23) can be removed. Especially if this is to become 'getting started'

It doesn't add anything; new users need to read through this page and will get to adv math functions. Numpy users can find that easily.

Yep, I agree...

andrewgsavage · 2024-04-30T22:48:08Z

doc/user_guide.rst

+Basic math with uncertain Variables
+=========================================
+
+:class:`Variable`s can be used in basic mathematical calculations


:class:[](https://lmfit.github.io/uncertainties/user_guide.html#id6)Variables

hasn't rendered correctly

will investigate (when moved to an api.rst, probably)

andrewgsavage · 2024-04-30T22:55:23Z

doc/user_guide.rst

-the functions from the standard** :mod:`math` **module**.  These
-mathematical functions are found in the :mod:`uncertainties.umath`
-module:
+Besides being able to apply basic mathematical operations to uncertaintties


uncertaintties > uncertainties

andrewgsavage · 2024-04-30T22:59:51Z

doc/user_guide.rst

+
+>>> print(x*y)
+240.0+/-76.83749084919418
+>>> (x*y).std_dev == (x*y).nominal_value *  sqrt((x.std_dev/x.nominal_value)**2 + (y.std_dev/y.nominal_value)**2 )


I'd introduce the .n and .s abbreviations early on (maybe at line 50?) and use them here to make this shorter.

OK, I was thinking maybe avoid .n and .s as they might be something to deprecate. I'm OK with fully embracing them as part of the API.

andrewgsavage · 2024-04-30T23:02:32Z

uncertainties/core.py

-    Objects are meant to represent variables that are independent from
-    each other (correlations are handled through the AffineScalarFunc
-    class).
+    Variablees are independent from each other, but correlations between them


Variablees >Variables

andrewgsavage · 2024-04-30T23:08:15Z

Looks good, how much more are you planning to do on this before merging? this + changelog are the last things to do before a new release.

newville · 2024-05-01T00:48:24Z

Yeah, how much more to do is a great question ;).

I might ask opinions all around (@wshanks, @jagerber48) on how complete this needs to be, and if the version at https://lmfit.github.io/uncertainties is approaching "acceptable".

andrewgsavage · 2024-05-01T10:42:03Z

I think the main thing is to remove anything python2 related + typos/formatting misses. Anything more is nice to have and can be done in a later PR.

It looks like you're roughly halfway through editing each of the files, with numpy and tech guide to go? Might as well continue through those.

I'd leave converting user guide -> getting started out of this PR to make it easier to review what's moved where and ensure nothings getting removed. There's enough moving in this PR already to keep track of!

newville · 2024-05-12T16:48:19Z

OK, sorry for the delay on this. I believe I have addressed most of the issues and this might be good enough, at least for a while. Suggestions? Again, rendered results are at https://lmfit.github.io/uncertainties

andrewgsavage · 2024-05-14T18:07:26Z

doc/install.rst

+The :mod:`uncertainties` package was written and developed by `Eric O. LEBIGOT
+(EOL)`_.  EOL also maintained the package until 2024, when the GitHub project
+was moved to the `lmfit GitHub organization`_ to allow more sustainable
+development and maintenance.  Currentt members of the devlopment and


andrewgsavage · 2024-05-14T18:13:12Z

doc/user_guide.rst


->>> import uncertainties
+To create a number with uncertainties or *Variable*, use the :func:`ufloat`
+function, which takes a *nominal value* ( (which can be interpreted as the most


Double open bracket

andrewgsavage · 2024-05-14T18:13:27Z

doc/user_guide.rst

+To create a number with uncertainties or *Variable*, use the :func:`ufloat`
+function, which takes a *nominal value* ( (which can be interpreted as the most
+likely value, or the mean or central value of the distribution of values), a
+*standard error* ( (the standard deviation or :math:`1-\sigma` uncertainty), and


Double open bracket

andrewgsavage · 2024-05-14T18:17:30Z

doc/user_guide.rst

+complicated.  That is, a Variable with a value of 25 +/- 10 might be greater
+than a Variable with a value of 24 +/- 8 most of the time, but *sometimes* it
+might be less than it.   The :mod:`uncertainties` package takes the simple
+approach of comparing.  That is


Of comparing nominal values.

andrewgsavage · 2024-05-14T18:27:21Z

There's some python 2 print statements in the tech guide

andrewgsavage · 2024-05-14T18:31:28Z

Also some python 2 print statements on the bumpy guide

andrewgsavage · 2024-05-14T18:31:33Z

Also some python 2 print statements on the numpy guide

andrewgsavage · 2024-05-14T18:37:06Z

Numpy*
There's also a ref to python2 on the numpy page.

For Python 2:

converters = dict.fromkeys(range(num_cols), uncertainties.ufloat_fromstr)

Other than that this looks and reads well. Id fix those then merge.

newville · 2024-05-15T01:39:28Z

@andrewgsavage Thanks!! OK, I think I have addressed hose spelling/print errors.

I am still investigating the "loadtxt" thing: "The code does what???"

newville · 2024-05-15T02:12:53Z

@andrewgsavage OK, I think the loadtxt/savetxt doc is correct now.

andrewgsavage · 2024-05-14T18:29:44Z

doc/formatting.rst

+
+.. Formatting method:
+
+More **control over the format** can be obtained (in Python 2.6+)


Python2 reference

newville · 2024-05-15T21:04:16Z

@andrewgsavage Thanks! Should we re-kindle the conversation about tagging and releasing 3.2.0?

andrewgsavage · 2024-05-15T21:20:13Z

Looks good, merged since there's been no indication anyone else will read through since you asked 2 weeks ago.

andrewgsavage · 2024-05-15T21:20:28Z

@andrewgsavage Thanks! Should we re-kindle the conversation about tagging and releasing 3.2.0?

yea please

newville added 2 commits March 14, 2024 20:45

WIP: cleanup of doc building

0855dfd

add yaml config for readthedocs

f55aee4

newville added 3 commits April 2, 2024 22:23

Merge branch 'master' into master

bc2825c

add .codecov.yml

8766f2e

add codecov token

cabd620

wshanks mentioned this pull request Apr 3, 2024

Move tests to tests folder #216

Merged

newville added 6 commits April 20, 2024 17:22

Merge branch 'master' of github.com:lmfit/uncertainties

a124d27

updating docs: layout and configuration

2566710

update pyproject config to allow more install options

0f34d54

update docstrings for ufloat and ufloat_fromstr

3810af0

updates for user_guide

929fb7f

simplify name for PDF doc, generate zip file of docs

c3c8cde

more doc work

6a0e887

andrewgsavage reviewed Apr 22, 2024

View reviewed changes

newville added 10 commits April 27, 2024 09:02

clean up makefiles

111ddfe

more updates

abb1ce6

move formatting doc

d6599c1

playing with themes, add sphinx_copybutton

7f877f3

add formatting to top bar

c8df1c5

index sidebar tweaks

337c8b1

more work on user guide

b6625f2

export Variable, improve its docstring

e55afe0

more user guide tweaks

f0b2607

more doc changes

a233ce2

more tweaks

12b6b6b

andrewgsavage reviewed Apr 30, 2024

View reviewed changes

newville added 4 commits May 12, 2024 11:36

add python-docs-theme requirement for docs

ac8c8f0

shorten, update formatting of function

d0db622

relabel technical guide as advanced topics, move api doc here

f99071d

more doc fixes

773bece

ran rstcheck by hand

71983bf

andrewgsavage reviewed May 14, 2024

View reviewed changes

doc fixes and spelling check as per @andrewgsavage review

02f3be1

update doc for savetxt/loadtxt

b1ae532

andrewgsavage approved these changes May 15, 2024

View reviewed changes

andrewgsavage merged commit 3255816 into lmfit:master May 15, 2024
18 checks passed


		.. Formatting method:

		More control over the format can be obtained (in Python 2.6+)

documentation building, readthedocs config #203

documentation building, readthedocs config #203

Conversation

newville commented Mar 15, 2024

codecov bot commented Mar 15, 2024 • edited Loading

Codecov Report

newville commented Apr 22, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andrewgsavage commented Apr 22, 2024

andrewgsavage commented Apr 22, 2024

newville commented Apr 23, 2024

andrewgsavage commented Apr 23, 2024 via email

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andrewgsavage commented Apr 30, 2024

newville commented May 1, 2024

andrewgsavage commented May 1, 2024

newville commented May 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andrewgsavage commented May 14, 2024

andrewgsavage commented May 14, 2024

andrewgsavage commented May 14, 2024

andrewgsavage commented May 14, 2024

newville commented May 15, 2024

newville commented May 15, 2024

Choose a reason for hiding this comment

newville commented May 15, 2024

andrewgsavage commented May 15, 2024

andrewgsavage commented May 15, 2024

codecov bot commented Mar 15, 2024 •

edited

Loading