# Documenter error \[:cross\_references\]

**URL:** <https://discourse.julialang.org/t/documenter-error-cross-references/105533>\
**Category:** General Usage\
**Tags:** documenter\
**Created:** [October 29, 2023, 11:39am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533 "2023-10-29T11:39:04Z")\
**Posts on this page:** 16\
**Page:** 1

<div class="post-metadata">

**Author:** ![Eben60](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eben60/32/13475_2.png) [@Eben60](https://discourse.julialang.org/u/Eben60)\
**Post date:** [October 29, 2023, 11:39am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/1 "2023-10-29T11:39:04Z")

</div>

I’d try to add a list of units and constants to Unitful - s. [issue 623](https://github.com/PainterQubits/Unitful.jl/issues/623) (filed by @rafaqz). AFAIU currently the only way to find the symbol used is to look into the source code of `pkgdefaults.jl`

The references are to be programmatically generated, but at first I set a mock-up file with the following contents

`
```@meta
DocTestSetup = quote
    using Unitful
end
```
``
# Default defined units and constants
``
## Basic dimensions
``
### Area
``
```@docs; canonical=false
Unitful.Area
```
``
#### Units
```@docs; canonical=false
Unitful.a
```
`

😅 - getting the code without rendering was not that easy - 😅

With that, I get an error from the `Documenter` make script:

```julia
ERROR: `makedocs` encountered an error [:cross_references] -- terminating build before rendering.
Stacktrace:
 [1] error(s::String)
   @ Base ./error.jl:35
 [2] runner(#unused#::Type{Documenter.Builder.RenderDocument}, doc::Documenter.Document)
   @ Documenter ~/.julia/packages/Documenter/nQAq5/src/builder_pipeline.jl:253
 [3] dispatch(#unused#::Type{Documenter.Builder.DocumentPipeline}, x::Documenter.Document)
   @ Documenter.Selectors ~/.julia/packages/Documenter/nQAq5/src/utilities/Selectors.jl:170
 [4] #79
   @ ~/.julia/packages/Documenter/nQAq5/src/makedocs.jl:248 [inlined]
 [5] withenv(::Documenter.var"#79#81"{Documenter.Document}, ::Pair{String, Nothing}, ::Vararg{Pair{String, Nothing}})
   @ Base ./env.jl:197
 [6] #78
   @ ~/.julia/packages/Documenter/nQAq5/src/makedocs.jl:247 [inlined]
 [7] cd(f::Documenter.var"#78#80"{Documenter.Document}, dir::String)
   @ Base.Filesystem ./file.jl:112
 [8] #makedocs#77
   @ ~/.julia/packages/Documenter/nQAq5/src/makedocs.jl:247 [inlined]
 [9] top-level scope
   @ ~/Julia/Unitful.fork/Unitful.jl/docs/make.jl:7

julia> 

```

It appears, only Units ( `Unitful.a,` `Unitful.b`, `Unitful.minute`) trigger the error - if I remove the second `@docs`, the first one (`@docs Unitful.Area`) will be happily processed.

All Units are properly documented, so I’m @ loss.

The whole context [on the Github](https://github.com/Eben60/Unitful.jl/tree/doc_units)

---

<div class="post-metadata">

**Author:** ![mortenpi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mortenpi/32/158_2.png) [@mortenpi](https://discourse.julialang.org/u/mortenpi)\
**Post date:** [October 30, 2023, 5:03am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/2 "2023-10-30T05:03:45Z")

</div>

Look for errors earlier in the logs. It looks like you’re trying to refer to a docstring that does not exist (or is not included) with at-ref in the `Unitful.a` etc docstrings.

---

<div class="post-metadata">

**Author:** ![Eben60](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eben60/32/13475_2.png) [@Eben60](https://discourse.julialang.org/u/Eben60)\
**Post date:** [October 30, 2023, 8:31am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/3 "2023-10-30T08:31:41Z")

</div>

```julia
help?> Unitful.a
  Unitful.a

  The are, a metric unit of area, defined as 100 m^2.

  Dimension: 𝐋^2.

  See Also: Unitful.m.

julia> 

```

The docstring appears to exist.

What does it mean “not included with at-ref” ?

My current guess, this unit is defined via macro, and therefore `Documenter` then can’t process it properly.

```julia
" Unitful.a
\nThe are, a metric unit of area, defined as 100 m^2.
\nDimension: 𝐋^2.
\nSee Also: [`Unitful.m`](@ref)."
@unit a "a" Are 100m^2 false

```

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [October 30, 2023, 10:04am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/4 "2023-10-30T10:04:55Z")

</div>

But it `@ref`s (that is what Morten meant) to `Unitful.m` but you do not have `Unitful.m` in your documentation?

---

<div class="post-metadata">

**Author:** ![Eben60](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eben60/32/13475_2.png) [@Eben60](https://discourse.julialang.org/u/Eben60)\
**Post date:** [October 30, 2023, 10:23am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/5 "2023-10-30T10:23:53Z")

</div>

The whole reference chain appears to have docstrings

```julia
help?> Unitful.a
  Unitful.a

  The are, a metric unit of area, defined as 100 m^2.

  Dimension: 𝐋^2.

  See Also: Unitful.m.

help?> Unitful.m
  Unitful.m

  The meter, the SI base unit of length.

  Dimension: Unitful.𝐋 .

help?> Unitful.𝐋
  Unitful.𝐋

  A dimension representing length.

julia> 

```

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [October 30, 2023, 10:36am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/6 "2023-10-30T10:36:58Z")

</div>

And if you manage to get `m` and `L` in there as well, does the error vanish? (I have no clue about your automatic generation where you wrote that it was not so easy to extract, but let’s say in your Mockup you add both in the last `@docs` block?)

---

<div class="post-metadata">

**Author:** ![Eben60](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eben60/32/13475_2.png) [@Eben60](https://discourse.julialang.org/u/Eben60)\
**Post date:** [October 30, 2023, 10:52am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/7 "2023-10-30T10:52:59Z")

</div>

> [@kellertuer](#):
>
> where you wrote that it was not so easy to extract

I’ve only meant if I paste the markdown source into Discourse it will get automatically rendered and that was not what I wanted, so I added quite a few `<code>` and `<br>` tags to get it.

The OP code was written manually and reproduced above literally.

I’d try your suggestion later on

---

<div class="post-metadata">

**Author:** ![Eben60](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eben60/32/13475_2.png) [@Eben60](https://discourse.julialang.org/u/Eben60)\
**Post date:** [October 30, 2023, 9:14pm UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/8 "2023-10-30T21:14:02Z")

</div>

If I include both these references as below, it works. The order is not important, but both other refs must be present.

````@docs; canonical=false`  
``

`
```julia
Unitful.a

Unitful.m

Unitful.𝐋

```
`

```` `

This is an interesting fact, but I don’t see how it can help me ☹

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [October 31, 2023, 5:46am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/9 "2023-10-31T05:46:58Z")

</div>

Well it explains the error message that you had above, you can not just list `Unitful.a` in the docs, since it references to `Unitful.m`, those docs have to be present as well, and hence also `Unitful.L`.  
So that resolves the error you started with.

Can you maybe explain a bit more why that does not help you?

---

<div class="post-metadata">

**Author:** ![Eben60](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eben60/32/13475_2.png) [@Eben60](https://discourse.julialang.org/u/Eben60)\
**Post date:** [October 31, 2023, 9:27am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/10 "2023-10-31T09:27:06Z")

</div>

> [@kellertuer](#):
>
> Well it explains the error message that you had above, you can not just list `Unitful.a` in the docs,

@kellertuer thank you, your explanation certainly helps - that was not clear to me.

The problem is, in `Unitful` there are about a thousand units defined and and provided with docstrings. Most of them are derived ones, like `µm`, `km`, and `Ym`.

Units are not listed in the documentation - which is what I want to improve on. I’d also document the physical constants provided by `Unitful`.

I’d like to document only non-derived units like `m` or `inch` - that is sufficient if you know how to prefix them. Otherwise the document would become to large and non-ergonomic to use. The only thing I want, that is to give the user a possibility to find the `Unitful`’s unit name for _minute_, _inch_, _candela_, _Avogadro’s constant_, etc. without searching for it in the package source.

Though most units would refer to the basic SI units (which are all included anyway), like `barn` refers to `m`, there are some edge cases, like `inch` referring to `cm`, of `g` referring to `kg`.

So now I’m thinking of extracting the docstrings programmatically, then strip them of the `@ref`s and include into the markdown file.

---

<div class="post-metadata">

**Author:** ![Eben60](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eben60/32/13475_2.png) [@Eben60](https://discourse.julialang.org/u/Eben60)\
**Post date:** [October 31, 2023, 10:17am UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/11 "2023-10-31T10:17:29Z")

</div>

> [@Eben60](#):
>
> So now I’m thinking of extracting the docstrings programmatically, then strip them of the `@ref`s and include into the markdown file.

An alternative solution could be to collect all these (directly and indirectly) referenced entities and put them into a separate section of the document (a hidden section maybe 😉 ).

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [October 31, 2023, 12:28pm UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/12 "2023-10-31T12:28:18Z")

</div>

You could write a small function in the docs before calling the `make.jl` before calling `makedocs` that generates such a markdown file and contains all units you would like to document?

---

<div class="post-metadata">

**Author:** ![Eben60](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eben60/32/13475_2.png) [@Eben60](https://discourse.julialang.org/u/Eben60)\
**Post date:** [October 31, 2023, 2:50pm UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/13 "2023-10-31T14:50:31Z")

</div>

Was it a question or suggestion?

Anyway, that (was | is | is partially implemented) my intention. “Small function” - depending on definition of “small”. I already have about 100 LOC, and it will probably become at least twice as much in the end.

So now if I am to add (in a separate section) documentation to all directly or indirectly referenced entities, just to satisfy `Documenter`’s constraints, it is going to explode exponentially, I’m afraid. I’d at least exclude those already referenced in the current documentation. Is there any practical possibility to get a list of such references?

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [October 31, 2023, 2:55pm UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/14 "2023-10-31T14:55:36Z")

</div>

More a suggestion, where I am maybe not 100% sure what your goal is and what your source of information.

Writing a file containing several lines of `Unitful.$(myLetter)` should be doable in a for loop (where you manually collect all units you want to document) – so that would in my head be \<20 lines – but probably more of a manual approach then what you do now.

A more automated approach – sure, could collect for the initial list all referenced `Unitful.Y` thingies and add them at the end as well – but also then I do not see the 100 LOC, but I probably miss what source of information you use in the beginning.

---

<div class="post-metadata">

**Author:** ![Eben60](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/eben60/32/13475_2.png) [@Eben60](https://discourse.julialang.org/u/Eben60)\
**Post date:** [October 31, 2023, 3:52pm UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/15 "2023-10-31T15:52:53Z")

</div>

Collect all documented non-derived units (there are many other entities in the package), sort them into basic dimensions (Length, Time…) and compound ones (Speed, Energy). That is a lot of filtering, mostly done, and took about 80 LOC. That is about half or third of the whole job. There are about 100 identifiers to be documented in a **well-structured** documentation page. That is already (almost too) much, and I’d like to avoid documenting other (referenced) identifiers just to get make working.

Producing a loop emitting 1000 lines of `Unitful.$(myLetter)` is surely easy, manually sieving the pile of garbage probably doable - but who will do it for the next package update?

The source of information is `Unitful.jl`, which is an otherwise well documented package with 946 downstream dependencies (i.e. about 10% of all Julia packages). My contribution to it till now amounts to one like on a github issue 🙂

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [October 31, 2023, 4:01pm UTC](https://discourse.julialang.org/t/documenter-error-cross-references/105533/16 "2023-10-31T16:01:24Z")

</div>

I see. Then I do not have a good idea how to fix the error directly – you could of course turn the error off, but then still the links in the docsstrings would not work.