Closed drdhaval2785 closed 3 years ago
This illustrates the difficulty in doing some things with Sphinx.
https://www.sanskrit-lexicon.uni-koeln.de/scans/csldev/csldoc/build/dictionaries/prefaces/schpref.html shows where in the final result these files are used.
If you look at generated source of 'schpref.html ', you see that the two links (to schpref/SCH-Nachtraege.pdf and schpref/SCH-Nachtraege.htm) resolve to files in two subdirectories of 'build/_downloads'. Specifically, the '09cca...' directory contains the pdf, and the 'b8141...' contains the htm.
It seems to me that sphinx is regenerating these at every build -- that's why there are two other directories ('937c68..' and '54475...') that contain same pdf and htm from a prior sphinx-build.
The source file /source/dictionaries/prefaces/schpref/schpref.rst is responsible for directing sphinx-build to make those _downloads files. and the links in schpref.html to those files. Specifically, the two lines:
Front matter as PDF :download:`schpref/SCH-Nachtraege.pdf`
Front matter as html :download:`schpref/SCH-Nachtraege.htm`
Only the latest version of those two directories is used in the build. Ideally, previous versions of the two directories would be removed by sphinx-build. Alternately, previous versions could be removed manually after a sphinx-build.
Basically it gets a lot of good press in the Python community.
The readthedocs project is built on sphinx, for instance. And there are many well-done examples in readthedocs.
However, there is a steep learning curve, in my experience, with sphinx. And I have never gotten over the hump in feeling really comfortable with it. So it is quite possible that the way I use sphinx in csldoc could be done in a better way by a sphinx expert. Or, it is possible that some other static site generator would be better for csldoc; there might even be a good one based on markdown.
https://github.com/rtfd/readthedocs.org/issues/3391#issuecomment-353909845 says to use relative path in downloads. Let us give it a try.
Corrected the documentation in sphinx. http://198.199.88.166/cologne/scans/csldev/csldoc/build/dictionaries/prefaces/schpref.html now has correct links to PDF and html files inside the ../../_static folder.
Corrected the documentation in sphinx. http://198.199.88.166/cologne/scans/csldev/csldoc/build/dictionaries/prefaces/schpref.html now has correct links to PDF and html files inside the ../../_static folder.
Front matter as HTML - SCH html was once made my be. @drdhaval2785 please advise, 1) I would like to link it from inside SCH to it, agree? 2) How can I upload a new file/version of http://198.199.88.166/cologne/scans/csldev/csldoc/build/_static/SCH-Nachtraege.htm if I would want to? 3) can I have text / left or bellow picture one http://198.199.88.166/cologne/scans/csldev/csldoc/build/dictionaries/prefaces/schpref/schpref02.html similar to https://sa.wikisource.org/ ?
I would like to link it from inside SCH to it, agree?
No problem.
How can I upload a new file/version of http://198.199.88.166/cologne/scans/csldev/csldoc/build/_static/SCH-Nachtraege.htm if I would want to?
You upload the new file at https://github.com/sanskrit-lexicon/csldoc/tree/master/source/_static in this github repository. The cologne test server just pulls this git repository and rebuilds the documentation by sphinx.
can I have text / left or bellow picture one http://198.199.88.166/cologne/scans/csldev/csldoc/build/dictionaries/prefaces/schpref/schpref02.html similar to https://sa.wikisource.org/ ?
Seems to be possible. You need to edit https://github.com/sanskrit-lexicon/csldoc/tree/master/source/dictionaries/prefaces/schpref pages 01.rst to 05.rst to have proper rst text.
Relative link for the pdf and html
@drdhaval2785 's solution much better than my original solution!
Definitely suggest this be installed at Cologne. Although I could do the installation, suggest you install this at Cologne when your login and permissions at Cologne are set up.
The cologne test server just pulls this git repository and rebuilds the documentation by sphinx.
Just to be clear, let me rephrase this description in a more long-winded way:
Currently, a 'cologne test server' is NOT at Cologne; rather it is some other machine, such as local Windows 10 computer. The details of setting up this test server are in the 'readme_dev.md' file of this
csldoc repository.
Changes are made in the 'source' directory of csldoc on the test machine.
Next, the 'sphinx-build' command remakes the 'build' directory on the test server, and the result is
examined locally (by looking at csldoc/build/index.html in a browser). When the local test version
is accepted, then the version of the csldoc repository on the test machine is pushed up to this GitHub sanskrit-lexicon/csldoc repository. Finally, either Dhaval or I login to Cologne server, navigate to the folder containing the Cologne version of this repository, and pull the revised repository. Once the new repository is pulled, it becomes the production version of the
'Documentation' link of the sanskrit-lexicon home page.
Suggest you install this at Cologne when your login and permissions at Cologne are set up.
Definitely will do that. This will give me some hands on experience of Cologne system.
The cologne test server just pulls this git repository and rebuilds the documentation by sphinx.
Got it.
pages 01.rst to 05.rst to have proper rst text.
Thanks for the hint. Seems like a lot of work.
Finally, either Dhaval or I login to Cologne server, navigate to the folder containing the Cologne version of this repository, and pull the revised repository
So it's a half-way stage, right? We would want to be able to command Cologne server from Github, right, @drdhaval2785 without any SSH?
command Cologne server from Github
At the moment, I don't view this as either possible or a goal. Have marked a TODO so this question will be reviewed later: https://www.sanskrit-lexicon.uni-koeln.de/doc/dokuwiki/doku.php?id=slfiles:docs:scans:csldev#how_to_modify_cologne_version
My understanding is that Github data will need to be pulled from Cologne server.
(On Cologne server from 'scans/csldev/csldoc' directory, we pull from Github (this pulls from https://github.com/sanskrit-lexicon/csl-doc/ . Note by @funderburkjim 12-13-2020)
No server would or should allow direct access from github, and even if a hack existed, it would be a severe security threat.
As soon as an erroneous commit is made, live server would get affected.
So it makes sense that the cologne live server should update from github when we are absolutely sure that the tests are passing and we have not broken any working functionality.
@funderburkjim, I do not remember whether I pushed this to Cologne server or not. Can you check it up?
Have marked a TODO so this question will be reviewed later: https://www.sanskrit-lexicon.uni-koeln.de/doc/dokuwiki/doku.php?id=slfiles:docs:scans:csldev#how_to_modify_cologne_version
Alive or not, but this URL is dead.
I do not remember whether I pushed this to Cologne server or not. Can you check it up?
I don't understand what needs to be checked.
Just to review ...
https://github.com/sanskrit-lexicon/csl-doc/blob/master/readme_dev.md
These instructions look up to date.
As stated at the bottom 'Install at Cologne' section:
You login to Cologne server via ssh, and make scans/csldev/csldoc current directory and 'git pull'.
This pulls from Github 'https://github.com/sanskrit-lexicon/csl-doc/' repository to Cologne server.
That's all to do.
See my clarification of first sentence of Dhaval's comment above of Jun 30, 2019
Currently, a 'git log' in 'scans/csldev/csldoc' at Cologne server shows:
git log
commit d76e668dd5903591e56b153dd7a04c2c3c92d602 (HEAD -> master, origin/master, origin/HEAD)
Author: funderburkjim <funderburkjim@gmail.com>
Date: Sun Nov 22 17:45:48 2020 -0500
minor edit to readme_dev.md
commit 67d0ac9b81f3fa3aa6c97b74e1de9600df365274
Author: funderburkjim <funderburkjim@gmail.com>
Date: Sun Nov 22 17:42:16 2020 -0500
LAN front matter
commit a62dfdbacf4dabc2eb9802920afab8132846e753
Author: funderburkjim <funderburkjim@gmail.com>
Date: Thu Nov 7 17:07:25 2019 -0500
add 'contrib.rst' for link to Github sanskrit-lexicon
commit 0003566948df74c45f162829fa9842e0cf72ad07
Author: drdhaval2785 <drdhaval2785@gmail.com>
Date: Fri Jun 28 11:28:25 2019 +0530
and some more
That commit '000356...' of Jun 28, 2019 by dhaval -- Looks like Dhaval DID push to Cologne.
Cronjob issue is already being tracked elsewhere.
https://github.com/sanskrit-lexicon/csldoc/tree/master/build/_downloads/09cca984256b9e8cf016eef03795270d https://github.com/sanskrit-lexicon/csldoc/tree/master/build/_downloads/54475f1de8e885e0e1002c4648c078ca Whenever I run the sphinx and there is some change, this file is regenerated in
build/_downloads/<commit_num>
folder.So is the case with https://github.com/sanskrit-lexicon/csldoc/tree/master/build/_downloads/9e7c68e748a0c9b272b71c57420e43fc and https://github.com/sanskrit-lexicon/csldoc/tree/master/build/_downloads/b8141a8956f3d5b4f0305ef54aa52082.