On Sun, Dec 15, 2024 at 7:22 PM Waldek Hebisch <de...@fricas.org> wrote: > > On Sat, Dec 14, 2024 at 02:38:35AM +0100, 'Ralf Hemmecke' via FriCAS - > computer algebra system wrote: > > 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. > > Well, fricas.github.io is nice and I value the work you put into it. > OTOH Sphinx IMO is a problematic dependency, so I would like to > have equivalent effect without using Sphinx. Also, I want more > functionality, some which looks impossible to get using Sphinx.
What's problematic about it, apart from a steep learning curve? Sphinx can do a lot of things; e.g. if you don't like .rst, you can use Markdown (.md); you can use dynamic building - calling your system to generate output and insert it into the docs you are building, etc. It's a de facto standard in the Python world, and very popular documentation tool for many other environments, too. Dima > > > 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. > > We can install dynamically generated pages at fricas.org, so this > is another option. But for me it is important to have local > documentation and I would like to include building API pages in > "standard" build, which is problematic due to dependencies (I > have now dependencies on my main work machine, but until recently > I could run build of API pages only on remote machine) and due > to build time. > > > 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). > > I hope that avoiding Sphinx will give at least as good and possibly > better result. Concerning API site, I am for keeping it as long > as is needed. If you think that Sphinx gives better result or > for whatever reason you want to use Sphinx for API site, that is > fine. I would like to avoid having needless duplication, and > have common code for all output formats, but intend to keep > Restructured Text as one of output formats. > > > > > 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. > > Yes. > > > > 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. > > The two are assentially the same thing, and yes I would like to > prowide this. Potentially troublesome is someting like (untested): > > ZMOD((systemCommand("system rm -rf /"); 3)) > > which (assuming I made no silly mistake) is supposed to "work" in > current HyperDoc and clearly I do not want to make accessible over > internet. > > There are simpler things, that I think are valuable: per operation > views ("full" with descriptions, signatures, grouped by conditon), > wildcards in operations names, filtering on number of arguments, > etc. For constructors ancestor views, descendants, etc. That > is quite a lot of small pages, giving just requested info and no > more. > > > > 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"? > > FriCAS book. > > > > I would like new convertor to handle FriCAS book. > > > > What exactly is your goal? > > To be able to present FriCAS book as HTML/XML. Thanks to > MathML format it should be reasonably easy to get static > version of examples from FriCAS book in XML. With good > convertor we should be able to produce HTML version of > actual text. > > > > > > 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. > > For me API search produces long list of results which I would have > to manually scan to get what I need. HyperDoc at top allow to specify > if I want a constructor, an operation or possibly wider search. > Once I get search result, there are possibilities to choose a view > and/or further filter to result. This is documented in FriCAS > book and for me quite useful. > > > Otherwise it might also make sense to just use > > google (as mentioned above). > > Google is sometimes surprisingly good if you give wrong (say > misspeled) query, but may be poor for exact match or for > conditions it does not undersatand. > > > 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. > > Hmm, would you like to write DLMF or Wolfram functions site in > reST? > > -- > 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 fricas-devel+unsubscr...@googlegroups.com. > To view this discussion visit > https://groups.google.com/d/msgid/fricas-devel/Z1-AtMqp7-VhVzci%40fricas.org. -- 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/CAAWYfq2hE0sfs8FhR_2uLfLzpzDid4rV1kTrK-2x0s66a6QFjQ%40mail.gmail.com.
