Sphinx doc

[Grégory Vanuxem]

Hello,

When I opened the fricas source directory in VSCode,  in an unknown manner, Sphinx doc were detected, several stuff were installed and html documentation was automagically generated. Good!

I know that the INSTALL file reads:

======
SphinxDoc (optional)

The documentation is built via Sphinx.

   sudo apt install python3 python3-pip
   pip3 install -U Sphinx==5.3.0

**WARNING**: Currently, Sphinx 6 and higher will fail building the
".html" pages.
=======

But, see the end of this mail, apparently the documentation was generated even if Sphinx v7.1.1 was used. Do not ask me what happened, I do not know. I can regenerate what happened though, I only had, by default, Python, and Makefile support in VSCode.

In fact the api link and api pages are not generated even if the other pages are generated. So I wonder if something can be done in this direction since, I discovered those pages recently on https://fricas.github.io/, I love this work and things in this direction seem to me interesting for the end user.

Any hints?

__

Greg

PS: I also attached a capture of generated HTML generated/rendered pages. Everything seems nicely hyperlinked from my little tests.

=======
This is the output of a VSCode language server, 'esbonio' (automatically installed in fact)
=======

[Log - 8:12:05 AM] Server start command: /bin/python3 -m esbonio
[Log - 8:12:05 AM] LanguageClientOptions: {"documentSelector":[{"scheme":"file","language":"restructuredtext"},{"scheme":"file","language":"python"}],"initializationOptions":{"sphinx":{"srcDir":null,"confDir":"","forceFullBuild":true,"numJobs":1,"buildDir":null},"server":{"logLevel":"error","logFilter":[],"hideSphinxOutput":false,"enableScrollSync":true}},"outputChannel":{"name":"Esbonio Language Server"}}
[Log - 8:12:05 AM] Starting Language Server
Running Sphinx v7.1.1
[Log - 8:12:08 AM] Build start.
building [mo]: targets for 0 po files that are out of date
writing output...

building [html]: targets for 12 source files that are out of date
updating environment:
[new config]
12 added, 0 changed, 0 removed
[2K
reading sources... [  8%]
citation

[2K
reading sources... [ 17%]
contributors

[2K
reading sources... [ 25%]
development

[2K
reading sources... [ 33%]
download

[2K
reading sources... [ 42%]
examples

[2K
reading sources... [ 50%]
faq

[2K
reading sources... [ 58%]
features

[2K
reading sources... [ 67%]
help

[2K
reading sources... [ 75%]
history

[2K
reading sources... [ 83%]
index

/home/greg/Git/jlfricas/src/doc/sphinx/source/index.rst:20: WARNING: toctree contains reference to nonexisting document 'api/index'
[2K
reading sources... [ 92%]
install

/home/greg/Git/jlfricas/src/doc/sphinx/source/install.rst:2: WARNING: Duplicate explicit target name: "fricas demos and tutorials".
[2K
reading sources... [100%]
spadstyleguide


/home/greg/Git/jlfricas/src/doc/sphinx/source/index.rst:20: WARNING: toctree contains reference to nonexisting document 'api/index'
/home/greg/Git/jlfricas/src/doc/sphinx/source/install.rst:2: WARNING: Duplicate explicit target name: "fricas demos and tutorials".
looking for now-outdated files...
none found
pickling environment...
done
checking consistency...
done
preparing documents...
done
copying assets...
copying static files...
done
copying extra files...
done
done
[2K
writing output... [  8%]
citation

[2K
writing output... [ 17%]
contributors

[2K
writing output... [ 25%]
development

[2K
writing output... [ 33%]
download

[2K
writing output... [ 42%]
examples

[2K
writing output... [ 50%]
faq

[2K
writing output... [ 58%]
features

[2K
writing output... [ 67%]
help

[2K
writing output... [ 75%]
history

[2K
writing output... [ 83%]
index

[2K
writing output... [ 92%]
install

[2K
writing output... [100%]
spadstyleguide


generating indices...
genindex
done
writing additional pages...
search
done
dumping search index in English (code: en)...
done
dumping object inventory...
done
build succeeded.

The HTML pages are in ../../.cache/esbonio/989fab4f1dd23c7a6c71b538026a063a/html.
[Log - 8:12:11 AM] Build complete {"config":{"sphinx":{"buildDir":"/home/greg/.cache/esbonio/989fab4f1dd23c7a6c71b538026a063a/html","confDir":"/home/greg/Git/jlfricas/src/doc/sphinx/source","doctreeDir":"/home/greg/.cache/esbonio/989fab4f1dd23c7a6c71b538026a063a/doctrees","forceFullBuild":true,"srcDir":"/home/greg/Git/jlfricas/src/doc/sphinx/source","command":["sphinx-build","-M","html","/home/greg/Git/jlfricas/src/doc/sphinx/source","/home/greg/.cache/esbonio/989fab4f1dd23c7a6c71b538026a063a/html","-E","-d","/home/greg/.cache/esbonio/989fab4f1dd23c7a6c71b538026a063a/doctrees"],"version":"7.1.1"},"server":{"enableScrollSync":true}},"error":false,"warnings":0}

[Ralf Hemmecke]

On 22.08.23 09:23, Grégory Vanuxem wrote:
> Hello,
>
> When I opened the fricas source directory in VSCode, in an unknown manner,
> Sphinx doc were detected, several stuff were installed and html
> documentation was automagically generated. Good!
>
> I know that the INSTALL file reads:
>
> ======
> SphinxDoc (optional)
>
> The documentation is built via Sphinx.
>
> sudo apt install python3 python3-pip
> pip3 install -U Sphinx==5.3.0
>
> **WARNING**: Currently, Sphinx 6 and higher will fail building the
> ".html" pages.
> =======

Maybe the warning is confusing, since indeed some of the .rst files are
translated to HTML, but as you recognized, the stuff under /api/ is
missing. Only after the release of 1.3.9 I figured out what the actual
problem was. (I spent quite some time to bisect the source tree of
sphinx-doc to find the exact commit that caused the problem with not
compiling our api stuff.

It is now corrected already in master by this commit.

https://github.com/fricas/fricas/commit/6ec7efff69a298350c28a58f91373079e98bf228

Is that enough to answer your mail?

Ralf

[Grégory Vanuxem]

Thanks! I'll look at this better. BTW I think the root INSTALL file
needs also to be updated to reflect this change.