On 12/4/24 02:20, Waldek Hebisch wrote:
On Mon, Dec 02, 2024 at 06:06:54PM +0100, 'Ralf Hemmecke' via FriCAS
- computer algebra system wrote:
On 12/2/24 00:38, Waldek Hebisch wrote:
http://wiki.fricas.org/public/api2.spad
I'd like to wait with my feedback until I see others (especially
those that USE https://fricas.github.io/api) say an opinion about
the produced output from api2.spad.
ATM api2.spad output can not serve as a replacement for output of
api.spad+sphinx, it still needs implementation of few essential
features.
Maybe our goals differ here. I want nice, attractive, heavily
hyperlinked and searchable documentation. Build-time is not my primary
focus. I agree that it takes long and probably sphinx it doing needless
scanning of the .rst files for whatever reason. I bet that there might
be an option to speed that up for our particular case. I was new to
sphinx when I started. I still believe it is better than translating
directly to HTML. I don't want to prevent you from continuing with your
direct .spad -> .html translation for nightly builds, but I would like
to keep the sphinx-generated output.
Concerning api.spad+sphinx markup, it seem to me that 'edit on
github' link is somewhat out of place for 'localdoc'. (I personally
do not use> it at all, but maybe other people use it).
Well, having such a link might lower the barrier for people reading the
documentation and spotting a typo. Just click, edit, and create a pull-
request. And that can also work with the locally generated code. Of
course you need an internet connection when you click on "edit on
github", but I hope that you see the intent.
Actually, I do not see it in Firefox (it shows up in Lynx), so it is
not clear to me how it is supposed to work (I do not think that Lynx
is main browser for viewing API pages).
Huh? Note that there are two different types of source for fricas.github.io.
(1) .rst files
(2) .spad files
For (1) there appears a "edit on github" link in the left column and
points to the .rst source on github.
For (2) I couldn't do that, since linking to the generated .rst file
makes no sense. I therefore generate a link that points to the
respective .spad file. And that link also appears at the top of each API
page, looking like "any.spad line 197 [edit on github]". And this also
is shown in Firefox. I don't understand why you would not see it.
I also noticed that when translating something like '\spad{reduce(f,
x, r)}' current output seem to be
<code class="docutils literal notranslate"><span
class="pre">reduce(f,</span> <span class="pre">x,</span> <span
class="pre">r)</span></code>
that is we get 3 separate 'span'-s. I think it would be better to
have
<code class="docutils literal notranslate"> <span
class="pre">reduce(f, x, r)</span></code>
or possibly even
<code>reduce(f, x, r)</code>
OK, that is real critisism and I agree. In fact, the rst2html translator
coming with sphinx does not introduce that.
First step to make the output nicer is to translate
\spad{foo}
into :code:`foo` instead of the current ``foo``. I have already a patch
that does that.
That splitting that you mentioned obviously happens because there are
spaces inside the :code:`foo bar` source. Some other transformation that
happens in sphinx is doing this splitting. I guess it is connected to
highlighting of inline code. We currently need no highlighting, so I
will be looking for a way to switch that off. Help is welcome.
Another things are self-links, do they serve any useful purpose?
What is your definition of "self-links"?
Do you mean the bread-crumbs line that shows the user where he is in the
hierarchy?
Another thing is 'permalinks'. IIUC a 'permalink' is supposed to be
a stable link, reliably giving "the same page". But as api site is
unversioned any link to it is really not a 'permalink'. So, do they
make any sense on generated pages?
Do you mean a link like this?
http://fricas.github.io/api/BasicType.html#basictype
That should be permanent as long as there is BasicType in FriCAS.
Another things is estetics versus usability. Currently in Firefox
main part of a page is divided into 3 strips.
> When there is not much information and one has big screen,> then this
layout looks nice. But it wastes about 30% of screen
area, which makes it much less usable on small screens.
OK, accepted. But there are other themes. For example, you can cange to
html_theme = 'alabaster'
in the file src/doc/tmp/sphinx/source/conf.py inside the build directory.
cd $builddir/src/doc/tmp/sphinx
rm -r build
make html
firefox build/html/index.html
That gives you output with responsive design and even the breadcrumbs
lines are gone. Maybe alabaster is not the best theme. I like the one
used here better...
https://doc.sagemath.org/html/en/reference/index.html
Does anyone know what theme they use?
Ralf
--
You received this message because you are subscribed to the Google Groups "FriCAS -
computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to fricas-devel+unsubscr...@googlegroups.com.
To view this discussion visit
https://groups.google.com/d/msgid/fricas-devel/9a47d7ef-2fd8-429d-b015-53cef5dcb098%40hemmecke.org.
