Make docs chapter on default units and physical constants #704
Conversation
|
bump |
There was a problem hiding this comment.
If this file is automatically generated, why are you checking it in?
There was a problem hiding this comment.
I am not sure I understand the question. What should be the procedure in this case and what can I do towards it?
There was a problem hiding this comment.
Delete the file and git ignore it?
There was a problem hiding this comment.
The workflow as I intended it is as following: The file defaultunits.md will be generated on package updates on local build of the documentation by the developer, who may want to look onto what changed. Then the file to be checked in just as every other documentation chapter. The docs/make.jl script includes a check if it run locally and will not re-build the defaultunits.md file on the CI server.
docs/make.jl on the CI server will check the Unitful package version, and will error, if the chapter has not been generated locally for this version
If this workflow is OK, then the file shouldn't be git-ignored. If you think it is better to have it generated on the CI server, it is necessary to adapt thedocs/make.jl script.
There was a problem hiding this comment.
docs/make.jlon the CI server will check theUnitfulpackage version, and will error, if the chapter has not been generated locally for this version
This means we would always have to bump the version at the same time we add a new unit/constant, right?
There was a problem hiding this comment.
I assume adding new units/constants is a new feature, meaning the (minor) version must bumped. Or what is the question?
There was a problem hiding this comment.
We may want to make several changes before releasing a new version. In that case, the development version would have the same version number as the last release, so the check that the versions match is useless. If we then later release a new version, we have to regenerate the file even though we (hopefully) already did that when we added the unit earlier (so the docs of the development version already contain the new unit).
But maybe that's fine. It will ensure that a released version always has a regenerated file, so we won't forget to add a new unit (of course, if the file is auto-generated every time the docs are built, that can't happen either). The current way has the benefit that the file can be edited before being checked in.
| | `Np` | Neper | | ||
| | `cNp` | Centineper | | ||
|
|
||
| ### "Dimensionful" logarithmic units |
There was a problem hiding this comment.
I wouldn’t call this “dimensionful” (dBFS is dimensionless). Maybe “Logarithmic units relative to reference levels”?
There was a problem hiding this comment.
Then maybe “Log units related to reference levels” to keep the title a bit shorter (and probably related, not relative - but I am never sure with my English)
docs/src/defaultunits.md
Outdated
| #### Lumen | ||
|
|
||
| ``` | ||
| Unitful.lm | ||
| ``` | ||
|
|
||
| The lumen, an SI unit of luminous flux, defined as 1 cd × sr. |
There was a problem hiding this comment.
This has the same dimension as cd (because solid angles are dimensionless), but I don’t think it should be in this section, because luminous intensity and luminous flux are different quantities. It’s probably easiest to just do this by hand (move it into a new subsection “Luminous flux” in the “Derived dimensions” (currently called “Compound dimensions”) section).
docs/src/defaultunits.md
Outdated
| #### ϵ0 | ||
|
|
||
| ``` | ||
| Unitful.ε0 | ||
| Unitful.ϵ0 | ||
| ``` | ||
|
|
||
| A quantity representing the vacuum permittivity constant, defined as 1 / (μ0 × c^2). |
There was a problem hiding this comment.
This is included twice (see line 900).
|
@sostock thank you a lot for the review. I have added a couple of comments, but actually I have little experience in github collaboration, and I am afraid if I start now trying to fix each point, I have every chance to screw it here and there and it would be just more work for you. Could you probably just change everything as you consider it proper? |
|
@Eben60 Yes, I can apply these changes myself. No problem! |
| (;basicdims, compounddims) = uids |> getphysdims |> physdims_categories | ||
|
|
||
| basic_units = unitsdict(basicdims, uids) | ||
| compound_units = unitsdict(compounddims, uids) |
There was a problem hiding this comment.
If I understand correctly, this only collects units of dimensions that were declared with @derived_dimension. If we add units whose dimension isn’t “named”, they won’t show up here.
Adding documentation page on default units and physical constants, as requested in #623, and a script for creation/updating such a page. The script is to be run on the local computer computer on each update of
Unitful- it will be called fromdocs/make.jlHere is the new chapter as HTML rendered page.
(The script code is written without a deep understanding of the
Unitfultype system and is probably not exactly beautiful. However it is not intended for the end user anyway, and the result of the script is easily controlled.)