bastikr / sphinx-julia Goto Github PK

Hello, first off, thank you for Sphinx-Julia!

Starting with 5bf850e using Sphinx-Julia via jl:autofile for our documentation (this file.) generates a lot of warnings, specifically hundreds of lines of WARNING: Inline strong start-string without end-string. and/or WARNING: Inline substitution_reference start-string without end-string.. The documentation does not seem to get recognized correctly and appears unformatted.

Hi, I'm really excited about the potential to use this with a julia package my team and I are developing. Have you tried to set this up in the ReadTheDocs build environment? (I just started looking at RTD today and am not yet very familiar with their build environment, but it seems like it might be somewhat complex to set it up with julia.)

If readthedocs is not suitable for building docs with this tool, can you give any recommendations for another build service that we could use (i.e. what do you use to build your documentation hosted on github.io?)

Thanks!

We have a Sphinx setup & theme which is currently used to build our documentation (http://julia.readthedocs.org/) which is available at https://github.com/JuliaLang/JuliaDoc. There have been some persistent issues because the domain inherits from the Python domain rather than starting from scratch, as you appear to have done.

Would it make sense to port the non-theme parts of this over to the repository under JuliaLang?

When trying to automatically import the whole content of a file via the :jl:autofile directive, file contents that are included via an include() statement and would otherwise be available to the julia interpreter are not recognized.

In my specific case it was a file declaring a module X which includes a file declaring module Y. Module X is then properly documented, whilst module Y is missing.

Attempting to explicitly import the module X.Y via the :jl:automodule directive raises the following error in juliautodoc.py's run() method:

ValueError: No matches for directive "module" in  file "<path_to_file>" with arguments ['X.Y']

Inspecting the way you implemented the parsing of julia files in the case of an active pyjulia installation led me to the conclusion that the parsetools.reader.read_file() function doesn't handle include statements yet.

I am using the 2.0 version alongside a julia installation with version 1.10.0