On Thu, Dec 05, 2024 at 09:31:00PM +0100, 'Ralf Hemmecke' via FriCAS - computer
algebra system wrote:
> 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.
Well, I prefer dynamically generated pages. I have tried a bit
search on API site and comparison with HyperDoc is that
HyperDoc clearly wins: HyperDoc offers several views with
filtering options, so it is not hard to get to desired info.
API search lumped thing together in rather inconvenient way.
API search probably could be improved, but I do not see possiblity
of offering customised views (like HyperDoc) in mostly static
site without creating inpracticaly large number of pages.
Theoretically you can re-implement HyperDoc functinality in
Javascript and do computations in the browser, but this seem
to be incompatible with Sphinx. And IMO undesirable, as this
would duplicate code that we already have and need.
So, IMO, good search needs dynamic "server-side" generated pages.
Another issue is testing. Ideally building API pages should
be routine part of building and testing. But this is problematic
both due to long time and because Sphinx has many dependencies.
Another thing is that I would avoid having many versions of code
that are doing similar things, but where no version is a complete
solution. Rather, I would like to have a single thing which
can produce classic HyperDoc pages, dynamic Html or (I you wich)
restuctured text.
> 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.
I suspect that it is not useful for 99.9% of people. And for
remaing ones it saves maybe 0.1% of work needed to create
sensible pull request. Simply, it is not clear if it is worth
file and screen space.
> > 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?
Sorry, it is there. Simply too many links have distracted me and
I somewhat "turned off".
> > 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.
Yes, code has and should have spaces. With proper HTML generator
that should be easy.
> 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?
Those too.
> > 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.
Well, this is really a self-links and AFAICS its permanence is no
better or worse than any other link inside the site. OK, BasicType
is likely to be there for long time, but several constructors are
gone and more will go away.
Such links make sense in a blog where top page changes frequently
and permalink allows to find the same page. Or in case of
versioned documentation, where documentation for version 24.12
contains links which point to 24.12, even when newer version
is current.
But in our case I see no usefule purpose: link that led to
page (or link shown by browser) will work as well. If you
think about spiders, I looked at logs of wiki site and
spiders happily index dynamic pages, so it seems to have
no real impact on them.
> > 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?
Trying various themes could be quite time consuming. It looks
easier to collect useful pieces of HTML/Javascript do get
something that we like (one reason for my question was that this
would be easier if you or somebody else could say "I want this
feature and this pieces of HTML gives it").
--
Waldek Hebisch
--
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 [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/fricas-devel/Z1T6lKxEb06N82be%40fricas.org.
