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. > 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.
