On Thu, Dec 28, 2023 at 05:53:50AM -0800, Aravindh Krishnamoorthy wrote: > Dear Ralf, > > This is my first post on this group. > > I'm a FriCAS user since a while and recently introduced FriCAS to a few > colleagues who are hackers (i.e. familiar with Mathematica, Python, Git, > etc.). Unfortunately, the entry bar is still quite high. IMHO this is > largely due to the incoherent and unmaintained documentation, especially > the "install" and "examples" sections of the website. Sorry; I understand > that this project is a community effort and everyone's doing their best. > But, the documentation definitely needs some improvement. > > I wanted to submit a PR to fricas/fricas.github.io: FriCAS documentation > <https://github.com/fricas/fricas.github.io> but noted that the actual > sources are scattered across "_sources", the repository fricas/fricas-doc: > Sources for documentation part of https://fricas.github.io > <https://github.com/fricas/fricas-doc> and other repositories. Furthermore, > the tooling (Makefile, etc.) to build the RST files to HTML pages is also > missing on fricas/fricas.github.io: FriCAS documentation > <https://github.com/fricas/fricas.github.io>.
I do not know what exactly is in <https://github.com/fricas/fricas.github.io>, but my impression was that this is merely a storage place for generated files. Concerning what is visible at <https://fricas.github.io/>, AFAICS bulk of it is 'book.pdf' and API pages. Both are generated from FriCAS sources and build infrastructure is in '<https://github.com/fricas/fricas/>, more precisely in the 'src/doc' subdirectory of the source tree. >From <https://fricas.github.io/install.html> subsection "Build extra documentation (book and website)": : The FriCAS home page can be built via : cd $BUILD/src/doc : make doc I did not check but IIUC when this finishes succesfully the 'html' subdirectory contains copy of the website. There are prerequisites for documentaion build, they are given in the section that I mention. There is a little subtlety in the above: <https://fricas.github.io/> contains documentaion for FriCAS-1.3.9, while if you fetch current sources from the trunk you will get documentation about trunk. In particular API changed: few functions are gone, there are new functions. If you build from current source most (hopefully all) broken links will be fixed. But since website is supposed to be about FriCAS-1.3.9, to fix it one needs to fetch 1.3.9 sources and apply the same fix to 1.3.9, rebuild documentaion and then upload to github. > If it would be kindly possible to reorganise the sources and provide the > tooling, I could actually edit the sources and submit a PR on > fricas/fricas.github.io: > FriCAS documentation <https://github.com/fricas/fricas.github.io> for your > review. Alternatively, you could also point me to where to find these and I > could reorganise everything myself in a PR. It it would be Ok, I want to > (especially) improve the "install" and "examples" (with broken links, etc) > sections a bit as a first step. Hmm, "install" clearly failed, as you did not find information how to rebuild documentation. The first step to contribute should be for you to repeat documentation build following instructions from the 'install.html' (plain text version is in the FriCAS source tree as 'INSTALL'). Source for 'install.html' (and 'INSTALL') is in 'src/doc/sphinx/source/install.rst', 'INSTALL' is generated using a script 'generate_INSTALL.sh', 'install.html' is created as part of general documentation build. BTW: You wrote "the website", but really there is no "the" here. Most up to date information is at SourceForge, <https://fricas.sf.net/>, but this is handful of pages for the rest linking to other sites. Github pages usually are updated at release time. <https://fricas.github.io/> contain API pages, but other pages are less up to date than SourceForge or Github project pages: on SourceForge I can update individual pages and there is only handful of them so it is easy to keep them up to date. <https://fricas.github.io/> requires build and some care to avoid unwanted changes, so it is updated less frequently. Well only Ralf updates <https://fricas.github.io/>, while I change sources I did no update to the site itself, one reason is that most changes should not go there (are about future release), the second reason is that since process is a bit involved I do not want to interfere with Ralf work. -- 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 on the web visit https://groups.google.com/d/msgid/fricas-devel/ZY2hw7Z5qIhyGI86%40fricas.org.
