Generated documentation for function modifies alignment of "unicode art"

Tooling Package Management
,
1

I’m working on publishing the documentation for a new package PSSFSS using Documenter.jl. Several of the function docstrings use “unicode art” to define the planar geometry and how it is parameterized (example below). When printed out at the REPL, in VScode, or in a Jupyter notebook everything looks great. However, the HTML generated by Documenter screws up the alignment of many lines, presumably because of some font issue? Is there a way to force Documenter to use JuliaMono or some other appropriate type face? Alternatively, can I substitute an actual PNG or SVG image in the Documenter-generated version of the docs while retaining the unicode art version in the REPL version?

Here is the sample:

"""
    jerusalemcross(;P::Real, L1::Real, L2::Real, A::Real, B::Real, w::Real, 
                 ntri::Int, units::PSSFSSLength, kwargs...)
 
# Description:

Create a variable of type `RWGSheet` that
contains the triangulation for a "loaded cross" type of geometry.
The returned value has fields `s₁`, `s₂`, `β₁`, `β₂`, `ρ`, `e1`, `e2`, `fv`, `fe`, 
and `fr` properly initialized.


The following "ascii art" attempts to show
the definitions of the geometrical parameters `P`, `L1`, `L2`, `A`, `B`, and `w`.
Note that the structure is supposed to be symmetrical wrt reflections
about its horizontal and vertical centerlines, and wrt reflections through a line oriented
at a 45 degree angle wrt the x-axis.


    ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ 
    ┃                                                       ┃ _______
    ┃               ┌────────────────────────┐              ┃    ↑
    ┃               │ ┌───────────────────┐  │              ┃    │
    ┃               │ └───────┐    ┌──────┘  │              ┃    │
    ┃               └──────┐  │    │ ┌───────┘              ┃    │
    ┃                      │  │    │ │                      ┃    │
    ┃  ┌───────┐           │  │    │ │            ┌──────┐  ┃    │
    ┃  │  ┌─┐  │           │  │    │ │            │ ┌──┐ │  ┃    │
    ┃  │  │ │  │           │  │   →│ │← w         │ │  │ │  ┃    │
    ┃  │  │ │  │           │  │    │ │            │ │  │ │  ┃    │
    ┃  │  │ │  └───────────┘  │    │ └────────────┘ │  │ │  ┃    │
    ┃  │  │ └─────────────────┘    └────────────────┘  │ │  ┃    
    ┃  │  │                                            │ │  ┃   L1 
    ┃  │  │ ┌─────────────────┐    ┌────────────────┐  │ │  ┃  
    ┃  │  │ │  ┌───────────┐  │    │ ┌────────────┐ │  │ │  ┃    │
    ┃  │  │ │  │           │  │    │ │            │ │  │ │  ┃    │
    ┃  │  │ │  │           │  │    │ │            │ │  │ │  ┃    │
    ┃  │  └─┘  │          →│  │    │ │← L2     B →│ └──┘ │← ┃    │
    ┃  └───────┘           │  │    │ │            └──────┘  ┃    │
    ┃                      │  │    │ │                      ┃    │
    ┃               ┌──────┘  │    │ └───────┐              ┃    │
    ┃               │ ┌───────┘    └──────┐  │              ┃    │
    ┃               │ └───────────────────┘  │              ┃    │
    ┃               └────────────────────────┘              ┃ ___↓___
    ┃               |<───────── A ──────────>|              ┃
    ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ 
    |<─────────────────────── P ───────────────────────────>|
                        
    
    
# Arguments:

All arguments are keyword arguments which can be entered in any order.

## Required arguments:
- `P`: The period, i.e. the side length of the square unit cell.
- `L1`,`L2`, `A`, `B`, `w`: Geometrical parameters as defined above.  Note that it is permissible
   to specify `w ≥ L2/2` and/or `w ≥ B/2` in which case the respective region will
   be filled in solidly with triangles.  If both conditions hold, then the entire structure will be
   filled in (i.e., singly-connected).  In that case the `L2` and `B` dimensions will be used 
   for the respective widths of the arms, and `w` will not be used.
- `units`:  Length units (`mm`, `cm`, `inch`, or `mil`)
- `ntri`:  The desired total number of triangles.  This is a guide/request, 
           the actual number will likely be different.
    
$(optional_kwargs)
"""

Thanks in advance for any help.

2

It’s possible to modify the style sheets used by Documenter to use different styles and fonts - you put copies of the CSS files into your assets folder, and Documenter will use them in preference to its default ones. The changes are few - have a look at GitHub - JuliaGraphics/ColorSchemes.jl: colorschemes, colormaps, gradients, and palettes if you want to see how I do it.

There are now some Documenter "theme’ packages too - GitHub - JuliaDiff/DocThemeIndigo.jl: The Documenter Theme for the ChainRules family of packages. But you can use it too is one.

You can generate PNG/SVG images during the Documenter build process - many packages do this - but they’ll have to be part of the main text, rather than in the docstring, so you’ll have both image and docstring…

If you generate multiple SVG images during the build, check that the text hasn’t got scrambled. (This will be fixed in the next release, apparently.)

1 Like
3

Using your stylesheets with your wonderful JuliaMono fonts did the trick. Thanks!

1 Like