search

sanskrit-lexicon / csl-doc

Development version of cologne sanskrit lexicon 'documentation'
1 stars 0 forks source link

SCH-Nachtraege regenerated on each commit #2

Closed drdhaval2785 closed 3 years ago

drdhaval2785 commented 5 years ago

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.

funderburkjim commented 5 years ago

This illustrates the difficulty in doing some things with Sphinx.

schpref.html

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.

schpref.rst

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`

How to improve?

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.

why did I choose sphinx?

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.

drdhaval2785 commented 5 years ago

https://github.com/rtfd/readthedocs.org/issues/3391#issuecomment-353909845 says to use relative path in downloads. Let us give it a try.

drdhaval2785 commented 5 years ago

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.

gasyoun commented 5 years ago

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/ ?

drdhaval2785 commented 5 years ago

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.

funderburkjim commented 5 years ago

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.

funderburkjim commented 5 years ago

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.

drdhaval2785 commented 5 years ago

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.

gasyoun commented 5 years ago

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?

funderburkjim commented 5 years ago

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

drdhaval2785 commented 5 years ago

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)

  1. No server would or should allow direct access from github, and even if a hack existed, it would be a severe security threat.

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

drdhaval2785 commented 3 years ago

@funderburkjim, I do not remember whether I pushed this to Cologne server or not. Can you check it up?

gasyoun commented 3 years ago

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.

funderburkjim commented 3 years ago

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.

funderburkjim commented 3 years ago

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

Dhaval DID push

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.

drdhaval2785 commented 3 years ago

Cronjob issue is already being tracked elsewhere.