Skip to content

Conversation

@Eben60
Copy link
Contributor

@Eben60 Eben60 commented Jun 24, 2025

This update primarily adds documentation on dimensions.
Other (minor) change: Physical constants now sorted ignoring case.

The PR is based on my another PR #704 , but can be merged independently.

Comment on lines 23 to 27
```
Unitful.Amount
```

Supertype for quantities and levels of dimension `Unitful.𝐍`
Copy link
Member

Choose a reason for hiding this comment

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

Use

Suggested change
```
Unitful.Amount
```
Supertype for quantities and levels of dimension `Unitful.𝐍`
```@docs
Unitful.Amount
```

? Here and everywhere else.

Copy link
Contributor Author

@Eben60 Eben60 Aug 31, 2025

Choose a reason for hiding this comment

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

@docs block apparently wouldn't generate documentation for non-exported objects. In any case in my tests I'm getting an error if trying it with Unitful.Amount or other internal object, whereas the following in the same place works as expected:

```
@docs; canonical=false
Unitful.Quantity
```

AI suggested some workarounds which may work or not work.

On the other side, the whole chapter had been generated by my script #704 from docstrings. Now dimensions were added, generated from docstrings as well. Thus I see no reason to treat them differently.

Copy link
Collaborator

Choose a reason for hiding this comment

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

I cannot confirm that docstrings for non-exported objects don’t get rendered. The problem with including only the Unitful.Amount docstring is that it contains a reference to Unitful.𝐍, so that docstring needs to be included as well. The following builds and renders fine for me:

```@docs
Unitful.Amount
Unitful.𝐍
```

I think that using @docs blocks has several advantages:

  1. Due to the rendering as blocks there is a stronger optical separation between the docstrings.
  2. Docstrings can be collapsed, which is nice on a page that contains so many of them.
  3. When building the docs there is a warning that lists all docstrings that are not included in the docs. That list currently contains all units, dimensions etc. Including them would make this list much shorter, so that it can actually be used to see what is still missing in the docs.
  4. Less code needed.

Copy link
Contributor Author

@Eben60 Eben60 Sep 1, 2025

Choose a reason for hiding this comment

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

OK, this way it works, so I'd adapt the script and generate updated version of the docs chapter in the next days. Thank you.

(both Gemini 2.5Pro and Claude 3.5 told me "the @docs block requires that the documented symbols be exported..." 😕 - and as it indeed thrown error, there was a reason to beleive them)

Copy link
Member

Choose a reason for hiding this comment

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

both Gemini 2.5Pro and Claude 3.5 told me "the @docs block requires that the documented symbols be exported..."

...

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Now updated, and docs build went without issues.

@giordano giordano requested a review from sostock September 1, 2025 21:43
@giordano
Copy link
Member

giordano commented Sep 1, 2025

Documentation build uploaded as artifact at https://github.com/JuliaPhysics/Unitful.jl/actions/runs/17387815527/artifacts/3901204474, so that people don't need to build locally to see the output.

#### Yard

```
Unitful.nm
Copy link
Collaborator

Choose a reason for hiding this comment

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

I realize that it’s ordered alphabetically, but I don’t like that nanometer is between mile and yard, and nowhere near meter. Generally, I’d prefer if the SI units are always the first in each section. But alphabetic order also makes sense.

I also don’t like that some prefixed units are included (because they are needed) and others are not. I would list all prefixed units after the corresponding non-prefixed unit, but in a collapsed section (like I suggested earlier). That could be added in a follow-up PR, it doesn’t need to happen now.

Copy link
Member

Choose a reason for hiding this comment

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

I'd leave this for a follow up PR if possible 🙂

@giordano giordano merged commit 3159e56 into JuliaPhysics:master Sep 3, 2025
1 check passed
@Eben60 Eben60 deleted the Def_units_docs_with_dims branch September 20, 2025 19:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants