Big docs reorganise and expand. #109

pp-mo · 2025-01-16T12:30:33Z

Closes #80
Refactored version of #105

Adds new sections on core data and general operations.
Integrates the how-to sections also

Todos:

prune for repetition.
review + clarify 4-way Diataxis-like top-level division =
- Getting Started (intro + tutorial)
- User Guide
- API
- Detail Notes
move existing details sections to "detail notes" sections (possibly with short hinting links)
add a how-to on chunking control
review for changes to equality provision (no comprehensive == on variable/ncdata)
re-proof-read all

…string data fix.

pp-mo · 2025-01-29T10:30:16Z

@trexfeathers welcome and thanks for looking !
if reviewing, scope here is really : do the docs structure and coverage generally look appropriate to you now (as a first proper attempt). i.e. notably

are there things badly misplaced
or plain missing
is it clear enough from the entry point level what is available + where to find things

Great also to have anyone else comment on this,
I think it's the only thing really needed now prior to v0.2 release (except release whatsnew drafting)

pp-mo · 2025-02-06T12:52:20Z

OK I have now reviewed all the API docs builds, fixed (hopefully) for correctness and updated, generally smoothed over and introduced some more cross-links into newer docs sections where it seemed obvious.

So I reckon this is up to scratch now, pending any suggestions about structural improvements.

trexfeathers

OK I've read most of it. It is impressively comprehensive 💐

To-do for @trexfeathers:

Review the details section
Consider the overall structure/approachability

docs/userdocs/user_guide/data_objects.rst

trexfeathers · 2025-02-06T14:50:34Z

docs/userdocs/user_guide/data_objects.rst

+
+:class:`~ncdata.NcData`
+^^^^^^^^^^^^^^^^^^^^^^^
+This represents a dataset containing variables, attributes and groups.


Suggested change

This represents a dataset containing variables, attributes and groups.

This represents a dataset containing variables, attributes and dimensions.

OK, but a dataset also contains groups, so I guess it should be both. Will fix ...

docs/userdocs/user_guide/data_objects.rst

trexfeathers · 2025-02-06T14:59:51Z

docs/userdocs/user_guide/data_objects.rst

+but **not** ``unit = dataset.variables['x'].attributes['attr1']``
+
+And not ``unit = dataset.variables['x'].attributes['attr1']``


Why are these identical?

Not sure, will fix!

docs/userdocs/user_guide/common_operations.rst

trexfeathers · 2025-02-06T16:15:10Z

docs/userdocs/user_guide/howtos.rst

+    >>> if "_fillvalue" in var.attributes:
+    >>>     var.attributes.rename("_fillvalue", "_FillValue")
+    ... 


Missing indenting

trexfeathers · 2025-02-06T16:17:33Z

docs/userdocs/user_guide/howtos.rst

+
+Load a file containing variable-width string variables
+------------------------------------------------------
+You must supply a ``dim_chunks`` keyword to the :meth:`ncdata.netcdf.from_nc4` method,


This Sphinx domain hasn't rendered, and would be quite useful for getting more detail.

trexfeathers · 2025-02-06T16:25:37Z

lib/ncdata/utils/_compare_nc_datasets.py


-    Accepts paths, pathstrings, open :class:`netCDF4.Dataset`\\s or :class:`NcData` objects.
+    Accepts paths, pathstrings, open :class:`netCDF4.Dataset`\s or :class:`NcData`


Sphinx domains not rendering

trexfeathers · 2025-02-06T16:29:50Z

lib/ncdata/threadlock_sharing.py

+.. NOTE::
+    This solution is at present still experimental, and not itself fully thread-safe,
+    so probably only suitable for top-level global application.


Not clear whether this is referring to everything, or just the context manager.

trexfeathers · 2025-02-06T16:34:03Z

docs/details/known_issues.rst

@@ -36,7 +43,7 @@ There are no current plans to address these, but could be considered in future
    * notably, includes compound and variable-length types

    * ..and especially **variable-length strings in variables**.
-      see : :ref:`string_and_character_data`
+      see : :ref:`string-and-character-data`, ref:`data-types`


Cross reference not rendering.

Co-authored-by: Martin Yeo <[email protected]>

Big rework and expand docs.

a51f251

pp-mo mentioned this pull request Jan 16, 2025

Lots more documentation #105

Closed

4 tasks

pp-mo changed the title ~~Big rework and expand docs.~~ Big docs reorganise and expand. Jan 16, 2025

pp-mo added 2 commits January 16, 2025 17:04

Lots more improvements + move sections.

5e81543

More fixes to correctness, consistency, readability. Add example for …

8b3c52a

…string data fix.

pp-mo requested a review from trexfeathers January 29, 2025 10:13

trexfeathers assigned trexfeathers and pp-mo Feb 5, 2025

Overhaul all API docstrings.

0e83165

trexfeathers requested changes Feb 6, 2025

View reviewed changes

pp-mo mentioned this pull request Feb 6, 2025

Numpy2 predocs #112

Draft

pp-mo and others added 9 commits February 6, 2025 17:35

Update docs/userdocs/user_guide/data_objects.rst

dce4b72

Co-authored-by: Martin Yeo <[email protected]>

Update docs/userdocs/user_guide/data_objects.rst

de38b89

Co-authored-by: Martin Yeo <[email protected]>

Update docs/userdocs/user_guide/common_operations.rst

10a6bee

Co-authored-by: Martin Yeo <[email protected]>

Update docs/userdocs/user_guide/common_operations.rst

cf79296

Co-authored-by: Martin Yeo <[email protected]>

Update docs/userdocs/user_guide/common_operations.rst

2356d12

Co-authored-by: Martin Yeo <[email protected]>

Update docs/userdocs/user_guide/common_operations.rst

872aa19

Co-authored-by: Martin Yeo <[email protected]>

Update docs/userdocs/user_guide/general_topics.rst

33232da

Co-authored-by: Martin Yeo <[email protected]>

Update docs/userdocs/user_guide/general_topics.rst

28b3ca3

Co-authored-by: Martin Yeo <[email protected]>

Update docs/userdocs/user_guide/general_topics.rst

eea69fb

Co-authored-by: Martin Yeo <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Big docs reorganise and expand. #109

Big docs reorganise and expand. #109

pp-mo commented Jan 16, 2025 •

edited

Loading

pp-mo commented Jan 29, 2025

pp-mo commented Feb 6, 2025

trexfeathers left a comment

trexfeathers Feb 6, 2025

pp-mo Feb 6, 2025 •

edited

Loading

trexfeathers Feb 6, 2025

pp-mo Feb 6, 2025

trexfeathers Feb 6, 2025

trexfeathers Feb 6, 2025

trexfeathers Feb 6, 2025

trexfeathers Feb 6, 2025

trexfeathers Feb 6, 2025

	This represents a dataset containing variables, attributes and groups.
	This represents a dataset containing variables, attributes and dimensions.

		but not ``unit = dataset.variables['x'].attributes['attr1']``

		And not ``unit = dataset.variables['x'].attributes['attr1']``


		Accepts paths, pathstrings, open :class:`netCDF4.Dataset`\\s or :class:`NcData` objects.
		Accepts paths, pathstrings, open :class:`netCDF4.Dataset`\s or :class:`NcData`

Big docs reorganise and expand. #109

Are you sure you want to change the base?

Big docs reorganise and expand. #109

Conversation

pp-mo commented Jan 16, 2025 • edited Loading

pp-mo commented Jan 29, 2025

pp-mo commented Feb 6, 2025

trexfeathers left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pp-mo Feb 6, 2025 • edited Loading

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

pp-mo commented Jan 16, 2025 •

edited

Loading

pp-mo Feb 6, 2025 •

edited

Loading