Please change https://doc.sagemath.org/index.html
kwankyu opened this issue · comments
Could we make this page
https://doc.sagemath.org/index.html
serve
$SAGE_ROOT/local/share/doc/sage/index.html
as any other page
serves
$SAGE_ROOT/local/share/doc/sage/*
Before there was no $SAGE_ROOT/local/share/doc/sage/index.html file. That seems to be the reason why only this page https://doc.sagemath.org/index.html serves a custom page. Now that $SAGE_ROOT/local/share/doc/sage/index.html file looks nice, there is no reason to have an exception.
Can I see the script that builds the contents served by https://doc.sagemath.org?
The page $SAGE_ROOT/local/share/doc/sage/index.html
looks like
I'll look into this, and see if this is possible or not.
What I don't know: is there a static copy of that root index.html page in Sage's source now? Why not use the script (with tweaks, if necessary) to automatically generate it?
Besides that, to make this work with the CDN, almost 500 more index pages are generated. Are they also part of the sage source code or will they be? Hardcoding all of them sounds like a bad idea as well.
There are also no links to the individual reference PDF documents. Is this intentional?
What I don't know: is there a static copy of that root index.html page in Sage's source now?
Yes, in the built Sage. It is a static html file. The source file is in $SAGE_ROOT/src/doc/en/website/root_index.html. It is just copied into $SAGE_ROOT/local/share/doc/sage/index.html when the documentation is built.
Why not use the script (with tweaks, if necessary) to automatically generate it?
The entries change very rarely. I saw no need to automatically generate it.
Does your script generate the file?
Besides that, to make this work with the CDN, almost 500 more index pages are generated. Are they also part of the sage source code or will they be? Hardcoding all of them sounds like a bad idea as well.
I don't understand this. What are those index pages? The page contains just 30 or so hyperlinks.
There are also no links to the individual reference PDF documents. Is this intentional?
It is in the reference manual top page if you follow the reference link in the PDF section.
Yes, in the built Sage. It is a static html file.
Ok, thank you for explaining that.
The entries change very rarely. I saw no need to automatically generate it.
True, but for me that's just a possible source of error. Besides all of that, the static index page is invalid HTML, which probably doesn't change much, but I would rather see this to be at least valid. Maybe the Sage project should make a ticket/PR, to at format the HTML well with an HTML formatter and iron out those invalid parts? Just a suggestion. (…and I don't claim the html code of the index page that's created here is valid either, just a quick solution to this problem)
Does your script generate the file?
Yes, see index.py ... It's meant to be a stopgap solution, until something better comes along.
Besides that, to make this work with the CDN, almost 500 more index pages are generated. Are they also part of the sage source code or will they be? Hardcoding all of them sounds like a bad idea as well.
I don't understand this. What are those index pages? The page contains just 30 or so hyperlinks.
I mean pages like this one: https://doc.sagemath.org/pdf/en/index.html
The point is, if there is no index.html page in a directory, you can't easily navigate around. I don't want users to click around and end up in a void. That's all.
It is in the reference manual top page if you follow the reference link in the PDF section.
Do you mean this page: https://doc.sagemath.org/pdf/en/reference/index.html ?
The pile of links to PDFs on the current root index page aren't great, they're hard to parse visually, but this page seems to be broken. I don't think that's a viable replacement right now.
pdf/en/reference/index.html
I looked into it, seems like the references to resources are broken. Part of the script I wrote fixes this for the html pages, at least, I think that's what it does (it's many years old). My working theory is the fix for the html pages does not cover fixing that page as well.
However, right now I don't have time to look into this deeper, but I'm now aware of this.
I also thank you for explanations. I now understand what you meant better.
True, but for me that's just a possible source of error.
Any error on that page will be fixed in sage source code. You don't need to worry about that. I will do :)
Besides all of that, the static index page is invalid HTML, ...
I don't know which parts you mean. If there are such parts, they are to be fixed.
I mean pages like this one: https://doc.sagemath.org/pdf/en/index.html
The point is, if there is no index.html page in a directory, you can't easily navigate around. I don't want users to click around and end up in a void. That's all.
By just clicking on a link, you do not land on one of those index pages. If you do, the link is a broken one.
I frequently visited https://doc.sagemath.org, but I never became aware of those index.html pages. But this thread is not about discussing the usefulness of those 500 more index pages.
It is in the reference manual top page if you follow the reference link in the PDF section.
Do you mean this page: https://doc.sagemath.org/pdf/en/reference/index.html ?
No. You should open the page from your local sage installation (after make doc-pdf). It looks like this
To understand how the documentation site work, let me ask
-
do you copy
htmlandpdfdirectories from../local/share/doc/sage/directory of a sage installation to yourdocumentationrepo that containsindex.py? -
then you run
index.pyto generate 500 more index pages. -
and then you push the
documentationrepo to CDNs?
I don't have a local install of Sage, I'll look into the specifics of why that index page does not work. I have a pretty good idea.
What this does is outlined in the readme
- I patch sources of Sage, just a little bit … at least in the past this was necessary, now it's probably fine as it is and build it.
- copy directories: yes, linked copies (doesn't matter). Rough steps are in the header comment of index.py
- yes, "index.py fix" first (to fix the relative links, and that's how I think that problem with the reference index page will be fixed) and then run "index.py" again. No matter if you saw those additional index pages ever or not, it's IMHO a good practice to not leave voids in the fabric of all pages – even if it is just for dumb robots indexing the pages :-)
- ad CDN: yes, it is called "github pages" and essentially served via Fastly.
Thanks.
I agree on your opinion on those additional index pages.
If you agree on making the online doc look like the screenshots (taken from the local doc) such that the local doc and the online doc look the same, then I can work on index.py for that. In this case, we use the static html for the top index page (but still generate the additional index pages).
Hi, I just worked on the 9.8 docs, still "the old way". I think we should revive this issue and work out if and how the new "website" stuff can be of use (and if there are blockers, to report them back upstream)
The PR provides the new way. Except that the script prepare.py does necessary copying of htmls and pdfs, it does the same housekeeping things like index.py, but uses the static root index file from sage so that doc.sagemath.org would provide the same documentation as sage.
@kwankyu just FYI, I wanted to look into this for 10.0 but had no time and got distracted. IMHO the main goal is to figure out what to copy or to write a small script to run. E.g. the symlink replacements in the index.py still need to happen.
OK. prepare.py is a direct replacement of index.py, and does exactly the same symlink replacements by the same code.