Comments (5)
I think this is a simpler example:
julia> module Foo
using DocStringExtensions
@template (FUNCTIONS, METHODS, MACROS) =
"""
$(SIGNATURES)
$(DOCSTRING)
"""
@doc raw"""
stuff
"""
foo() = 1
end
Main.Foo
help?> Main.Foo.foo
stuff
I was expecting the docstring at the end to have the signature added. This is DocStringExtensions v0.7.0 and Julia 1.1.0.
More generally, I need raw"..."
or doc"..."
docstrings since I tend to use lots of Latex. I don't currently see any way to make that work with this package due to this bug, but maybe there's a way I'm missing?
from docstringextensions.jl.
Do you have a code snippet of what you mean by any chance?
from docstringextensions.jl.
Ok a simple example that doesn't actually need the @__doc__ macro
but illustrates the problem:
module DocsCheck
using DocStringExtensions
@template TYPES =
"""
$(TYPEDEF)
$(DOCSTRING)
"""
macro documentbreaker(ex)
:(Base.@__doc__ $(esc(ex)))
end
"Docs don't show typedef"
@documentbreaker struct BrokenDocs <: AbstractString
s::String
end
"Docs show typedef ^"
struct WorkingDocs <: AbstractString
s::String
end
end
Then:
help?> DocsCheck.WorkingDocs
struct WorkingDocs <: AbstractString
Docs show typedef ^
help?> DocsCheck.BrokenDocs
Docs don't show typedef
julia>
from docstringextensions.jl.
@marius311, I think I may have found a workaround:
"""$(raw"""
stuff
""")"""
foo() = 1
My rough understanding of why this works is that the relevant DocStrExtensions code path (namely, a call to DocStrExtensions.format
) is used only when the docstring shows up as a :string
node in the AST (e.g. (string "x = " x)
, not a bare literal like "a"
).
I am combining this with a different workaround, to get Documenter.jl to use the right "view source" link when combined with Base.@kwdef
(rather than linking to the source of whatever name happens to first appear in the expansion of @kwdef
):
@doc """Fields:
$(FIELDS)$(raw"""
---
Prose documentation with ``\LaTeX``
""")""" MyStruct
@kwdef struct MyStruct
n::Int
end
from docstringextensions.jl.
I wonder if the above workaround (or a better version of it, if known) should be mentioned in the documentation? It seems like an important use case.
from docstringextensions.jl.
Related Issues (20)
- How to use alias of AbstractArray instead of the full name? (Feature request) HOT 2
- Display parametric types in a better way? HOT 2
- Remove documentation page for v0.1
- Update CI badges in the README HOT 2
- TagBot trigger issue HOT 7
- The `TYPES` template does not apply to parametric types
- MODULES key not found for `@template` HOT 1
- Doctest failures
- Format docstrings HOT 4
- Considering writing a script to add function signatures to a code base. HOT 5
- Examples of how to use all of the functionality HOT 5
- expected test failure from the incoming `Core.Compiler` changes HOT 3
- Cannot get source for generated functions
- feature request: non-api doc marker HOT 7
- How to show default values and types of keyword arguments? HOT 1
- Update docs to latest version of Documenter HOT 5
- different abbreviations for concrete and abstract types HOT 1
- FUNCTIONNAME inside a function that generates the docstring HOT 7
- Would it be possible to add a TYPEDMETHODLIST abbreviation HOT 2
- Internal errors when (ab)using `@template` HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docstringextensions.jl.