Opened 12 years ago

Closed 12 years ago

#4370 closed enhancement (wontfix)

[with patch, needs work] Add ability to clone the doc repository

Reported by: cremona Owned by: GeorgSWeber
Priority: major Milestone: sage-duplicate/invalid/wontfix
Component: documentation Keywords:
Cc: Merged in:
Authors: Reviewers:
Report Upstream: Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Status badges

Description

It would be very useful to be able to clone the documentation repository as well as the source repo. As Minh Van Nguyen said:

Is there a corresponding command or process that I can use to clone the
doc-main repo as well?

Whenever I review the official documentation that's shipped with each
Sage release, I would go into

<sage-home>/devel/doc-main

and then review the documentation from there. If I'm reviewing someone's
patch to any file in the latter directory, I would not clone doc-main
(since I don't yet know how to do that). Instead, I would go ahead with
applying the patch and then do more review of the patch. At this point,
at least one of two things can happen:

[1] If the patch gets a positive review, then all is fine and good.

[2] However, in case there's something wrong with the patched file and I
want to un-apply the patch, I would do this:

sage: hg_doc.revert()

This command reverts back to the stage at which the file in question is
unpatched.

Another possibility is for me to copy a source distro to more than one
directory, and then build (and test) the distro from those different
directories. That way, I would have a copy of Sage that I can use and
with which I won't apply any documentation patches. And I would also
have another copy of Sage for applying documentation patches. Building
one copy of a source distro usually takes a _very_ long time on each
machine that I have access to --- and running all standard tests further
add to my waiting time. As you can imagine, repeating the build and test
processes on the same machine for another copy of the same source distro
would further add to the waiting time. (Man, I can't wait to work on
Sage ;-)

and as mabshoff replied:

it is fairly simple to add a clone command for the doc repo. If you
want it just open a ticket and someone will take care of it. You can
even try yourself - just look at local/bin/sage-clone and ignore
nearly everything toward the end since that deals with build file
issues.

I think this will encourage people to add / improce the existing docs and to review enhancements of the docs.

Attachments (3)

4370-sage_scripts.patch (8.3 KB) - added by GeorgSWeber 12 years ago.
applies independently, but the other two are highly recommended first
4370-doc.patch (3.2 KB) - added by GeorgSWeber 12 years ago.
obsoleted, don't use (moved to #4441 upon request of the reviewer)
4370-sage_library.patch (2.0 KB) - added by GeorgSWeber 12 years ago.
obsoleted, don't use (moved to #4442)

Download all attachments as: .zip

Change History (13)

comment:1 in reply to: ↑ description Changed 12 years ago by mvngu

  • Owner changed from tba to mvngu
  • Status changed from new to assigned

Replying to cremona:

It would be very useful to be able to clone the documentation repository as well as the source repo.


Indeed.
+1 for your comment

and as mabshoff replied:

it is fairly simple to add a clone command for the doc repo. If you
want it just open a ticket and someone will take care of it. You can
even try yourself - just look at local/bin/sage-clone and ignore
nearly everything toward the end since that deals with build file
issues.

I think this will encourage people to add / improce the existing docs and to review enhancements of the docs.


I'll try to figure out how to implement the suggested clone command. Since I often work with the doc-main directory tree, this is more for my personal benefit. Of course, suggestions are always welcome.

comment:2 Changed 12 years ago by mvngu

  • Owner changed from mvngu to tba
  • Status changed from assigned to new

comment:3 Changed 12 years ago by GeorgSWeber

  • Owner changed from tba to GeorgSWeber
  • Status changed from new to assigned

Hmph,

that is a bit more work than I expected. I got "sage -clonedoc", "sage -bdoc" and "sage -branchdoc" already to work fine. However, obviously there are some fixes needed to get the documentation for 3.2.alpha2 texing (unescaped # in at least two different new patches). I'll see to that in another ticket. Next comes the update to hg.py so that hg_doc works (again). There would be documentation fixes needed, too (in the programming guide), but that is probably best yet another ticket.

Changed 12 years ago by GeorgSWeber

applies independently, but the other two are highly recommended first

comment:4 Changed 12 years ago by GeorgSWeber

  • Milestone changed from sage-3.2.1 to sage-3.2
  • Summary changed from Add ability to clone the doc repository to [with patch, needs review] Add ability to clone the doc repository

Well, the hg.py patch is not ready yet, but the three patches attached already fulfil all the requirements of this ticket. So you can give it a review already now.

The three patches are for three different repos: devel/sage, devel/doc, and finally local/bin.

After applying the patch to devel/doc, you have to do there once:

chmod a+x needed_additions_Sage-3.2.alpha2_doc-repository

./needed_additions_Sage-3.2.alpha2_doc-repository

(Writing that script was faster than trying to explain what to do with words.)

comment:5 Changed 12 years ago by GeorgSWeber

Forgot to add:

If someones really needs the possibility to clone the doc repo not on shell level, but inside sage using hg.py, please open another ticket for it, because it will take me quite some while before I will be able to sacrifice the time needed to finally adapt hg.py, thanks!

comment:6 Changed 12 years ago by mabshoff

  • Milestone changed from sage-3.2 to sage-3.2.1

Hi Georg,

4370-sage_library.patch should go to its own ticker since it is independent.

I would also not per default build the Sage documentation on clone - we do not do this for the sage library repo itself.

I can't see seem to fine the alleged possibility to clone the sage-scripts repo. Either way, I would not recommend that we allow this since there are numerous binaries in the bin directory and switching back and forth between various bin directories can cause subtle bugs at runtime.

Another thing I would like to wait for is the switch to the ReST documentation before we allow cloing the doc repo.

In the end I don't think this should be merged into 3.2 :(.

Cheers,

Michael

Changed 12 years ago by GeorgSWeber

obsoleted, don't use (moved to #4441 upon request of the reviewer)

Changed 12 years ago by GeorgSWeber

obsoleted, don't use (moved to #4442)

comment:7 follow-up: Changed 12 years ago by GeorgSWeber

  • Summary changed from [with patch, needs review] Add ability to clone the doc repository to [with patch, needs work] Add ability to clone the doc repository

Hi Michael, thanks for the review!

4370-sage_library.patch should go to its own ticker since it is independent.

Done, it is now #4441. I also moved the congroup.py patch away to #4442.

I would also not per default build the Sage documentation on clone

OK. I will address that in an update.

  • we do not do this for the sage library repo itself.

You're wrong here. See lines 68-91 of the "sage-clone" script, where explicitly "sage -b branch" is called. But let's clone the doc dir without (re-)build, OK.

I can't see seem to fine the alleged possibility to clone the sage-scripts repo. Either way, I would not recommend that we allow this since there are numerous binaries in the bin directory and switching back and forth between various bin directories can cause subtle bugs at runtime.

Ah, misunderstanding! I meant that the patch-files attached are to applied themselves to these three different repos, not more. I totally agree that cloning "$SAGE_ROOT/local/bin" would be a bad idea. But the content of the patch(es) did not and will not allow for that.

Another thing I would like to wait for is the switch to the ReST documentation before we allow cloing the doc repo.

Well. It might be helpful for the ReST documentation deployment.

In the end I don't think this should be merged into 3.2 :(.

Fine, at least for me.

comment:8 in reply to: ↑ 7 Changed 12 years ago by mabshoff

Replying to GeorgSWeber:

  • we do not do this for the sage library repo itself.

You're wrong here. See lines 68-91 of the "sage-clone" script, where explicitly "sage -b branch" is called. But let's clone the doc dir without (re-)build, OK.

You are right, but "sage -b" on an uptodate repo only rebuilds libcsage.so, so the build is more or less instant. Building the documentation takes *forever* with the current toolchain, but ReST will fix that.

Cheers,

Michael

comment:9 Changed 12 years ago by GeorgSWeber

Work on this ticket will be resumed after the move to ReST is completed.

comment:10 Changed 12 years ago by mabshoff

  • Milestone changed from sage-3.2.1 to sage-duplicate/invalid/wontfix
  • Resolution set to wontfix
  • Status changed from assigned to closed

The new documentation will reside in the main Sage repo, so this is a wontfix.

Cheers,

Michael

Note: See TracTickets for help on using tickets.