On 12/14/24 00:00, Waldek Hebisch wrote:
as static pages. Simply, instead of pr-generating inpractically
large number of pages sever may generate them on the fly.
Maybe, there are different people that have different goals...
Perhaps it would be useful to clarify what each of us wants and perhaps
it makes more sense not to work against each other. To say the truth, at
the moment I feel as if you do not value the work that I put into
fricas.github.io and rather aim at creating your own way to generate
documentation and get rid of what I did. I hope you understand that this
wouldn't make me happy.
Yes. I do not like HyperDoc and this is just because it feels like old
technology and *I* do not want to spend time on it. But FriCAS is an
open-source project, so everyone can do whatever he/she likes.
Not liking HyperDoc does not mean that I am against a system that
generates API pages from within a FriCAS session locally.
When I started with the sphinx pages, I had the explicit goal to bring
the API as static pages to the web. Goal 1: more visibility of FriCAS.
Goal 2: searchable by this sphinx generated search field and also by any
search engine. For example enter "Module site:fricas.github.io" into google.
Yes, sure HyperDoc is better when it comes to specifying domain/
category/package parameters and retrieve information for such particular
case. Still, HyperDoc looks so old-fashioned that I basically never use
it. If I could do the same stuff locally with my webbrowser, it would
improve the situation.
I basically see need for (1) static web pages (versioned for each
release) and (2) a local help/documentation system that helps from
within a FriCAS session (even without Internet access).
I would like to work on (1). Generation time of such web pages is not a
high priority. I have anyway a local service running that checks whether
the webpages still compile fine each time someone commits
something to the official git-repo.
You mentioned a few issues like to many <pre> stuff etc. or sidebars
that use too much space. Well, yes, that can and should be improved, but
that doesn't mean that we/you should *replace* the sphinx generated
pages by server-side generated HTML pages. If you want to create such a
system, do so, but do not ask for removing static pages (I somehow have
the impression that such would be your long term goal -- if it is not
then I apologise).
As for execution over the web. Yes that is dangerous, but if you find a
way to provide it, then do so. My approach rather is to provide a git-
repository of notebooks (for example
https://fricas.github.io/fricas-notebooks/FriCAS-LinearAlgebra.html)
that people can see and download and then modify.
Actually, jFriCAS can probably be made to provide an online FriCAS
service. I haven't yet experimented with it, because also that might
require to start a virtual machine on a server so that no harm can be
done to the server itself. At the moment static notebooks are a good
"first step".
'axiom-wiki' has three releated problem: - it depends on LaTeX wiki
software, which is unmaintained for many years, - via LaTeX wiki it
depends on Zope which stores data as a binary blob which only Zope
can read, - Zope rather frequently changes in incompatible ways.
I think FriCAS has too many different forms of documentation. I would
rather be in favour of migrating to just one or two forms and thus
reduce the maintenance work. But as long as there is someone (other than
me) willing to invest time, even that is not a big problem for me.
Would it be possible to retain https://fricas.github.io/ for what
it does now and just link to the dynamic pages for things like:
searching function names or live execution of examples.
Yes.
Yes, that sounds like a good approach.
In practice I wonder how useful live execution of examples is?
Its hard enough/impossible to get people to write even minimal
documentation and this live execution would be a lot more work on
top of that. So realistically, is it likely to increase beyond
the small number of examples already in HyperDoc?
Not so small if you count FriCAS book.
Eventually, we should also have the FriCAS book in HTML format on the
web and maybe even with links to notebooks that one can download and
execute.
Concerning usefulness, I think that this is useful, but I want to
get other things working with HTML first, especially search.
Can you be a bit more precise? Do you mean for example "search for
exported functions in Foo(R) where a user can set R==Integer" or "search
for the domain/package that implements function foo from domain Foo(R)
where R is Fraction(Integer)"? Such things I would really appreciate and
that wouldn't be a big security issue.
HyperDoc currently handles FriCAS book in C code (FRICASsys is only
involved in live examples). 'api.spad' contains convertor from
LaTeX susbset used in docstings to Restructured Text. IMO the
approach will not scale up to more complex tasks, so I want a
different convertor.
What are the "more complex tasks"?
I would like new convertor to handle FriCAS book.
What exactly is your goal?
Well, concerning API pages: negative part is that I do not see
how we can get good search using current technology (that is
Sphinx).
The question is what you understand by "good search". I have not taken
much effort to tailor the stuff that sphinx produces by default.
I find that search field useful enough (not perfect) to get to the
information I want. Otherwise it might also make sense to just use
google (as mentioned above). And yes, search for specified parameters on
parametrized domains would be super-cool and certainly nothing that
sphinx can or should deliver.
Also, I find build time problematic. I would like to resolve
those problems, and I think that direct generation of HTML can
resolve both problems.
I also think that the build time is too long. If someone can help in
finding the reason for this, I'd appreciate. But removing sphinx would
be a step into the wrong direction. No problem if you provide api2.spad
generated html documentation on fricas.org.
So I guess you want all the official documentation to be derived
from some common root?
Yes, exactly.
And for that it would be a good idea to agree upon a format that is both
readable in source code (++ docstrings) and has enough information to
generate good looking webpages from it. I'd really prefer reST over
HyperTex.
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/2e4a07b8-648e-4ed7-a6b6-44694a390f64%40hemmecke.org.
