Skip to content

Commit a8a6485

Browse files
author
Release Manager
committed
gh-38943: Some documentation improvement Just improve some documentation. Apparently the existing documentation uses the absolute URL `` * - `Tutorial <../tutorial/index.html>`_`` e.g. `sage/src/doc/en/developer/sage_manuals.rst`, none of them uses `<tutorial>`. I tried using `<chapter-tutorial>` in https://github.com/s agemath/sage/commit/955a09e746c7d9675d2a4c4f10558cec8d3eb948 but for some reason it doesn't work, so I just end up deleting it. ### 📝 Checklist <!-- Put an `x` in all the boxes that apply. --> - [x] The title is concise and informative. - [x] The description explains in detail what this PR is about. - [x] I have linked a relevant issue or discussion. (not aware of one) - [x] I have created tests covering the changes. - [x] I have updated the documentation and checked the documentation preview. ------ test failures have nothing to do with the change, see #37295 URL: #38943 Reported by: user202729 Reviewer(s): Kwankyu Lee, user202729
2 parents a65c0b1 + 6267b0d commit a8a6485

File tree

10 files changed

+52
-24
lines changed

10 files changed

+52
-24
lines changed

src/doc/en/developer/coding_in_cython.rst

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -32,13 +32,13 @@ up-to-date information or check out the
3232
to get started immediately.
3333

3434

35-
Writing cython code in Sage
35+
Writing Cython code in Sage
3636
===========================
3737

3838
There are several ways to create and build Cython code in Sage.
3939

40-
#. In the Sage Notebook, begin any cell with ``%cython``. When you
41-
evaluate that cell,
40+
#. In the Sage notebook or the Sage command line, begin any cell with
41+
a line containing ``%%cython``. When you evaluate that cell,
4242

4343
#. It is saved to a file.
4444

@@ -53,22 +53,21 @@ There are several ways to create and build Cython code in Sage.
5353
program that was compiled to create the ``.so`` file.
5454

5555
#. A ``cpdef`` or ``def`` function, say ``testfunction``, defined in
56-
a ``%cython`` cell in a worksheet can be imported and made available
57-
in a different ``%cython`` cell within the same worksheet by
56+
a ``%%cython`` cell in a worksheet can be imported and made available
57+
in a different ``%%cython`` cell within the same worksheet by
5858
importing it as shown below::
5959

60-
%cython
60+
%%cython
6161
from __main__ import testfunction
6262

63-
#. Create an ``.spyx`` file and attach or load it from the command
64-
line. This is similar to creating a ``%cython`` cell in the
65-
notebook but works completely from the command line (and not from
66-
the notebook).
63+
Refer to :meth:`sage.repl.ipython_extension.SageMagics.cython`.
64+
65+
#. Create an ``.spyx`` file and attach or load it
66+
from the command line.
6767

6868
#. Create a ``.pyx`` file and add it to the Sage library.
6969
Then run ``sage -b`` to rebuild Sage.
7070

71-
7271
Attaching or loading .spyx files
7372
================================
7473

src/doc/en/reference/repl/index.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
1+
.. _section-command-line:
2+
13
The Sage Command Line
24
=====================
35

46
The Sage Read-Eval-Print-Loop (REPL) is based on IPython. In this
57
document, you'll find how the IPython integration works. You should
68
also be familiar with the documentation for IPython.
79

8-
For more details about using the Sage command line, see the Sage
9-
tutorial.
10+
For more details about using the Sage command line, see `the Sage
11+
tutorial <../../tutorial/index.html>`_.
1012

1113
Running Sage
1214
------------

src/doc/en/tutorial/index.rst

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,6 @@
22
You can adapt this file completely to your liking, but it should at least
33
contain the root `toctree` directive.
44
5-
.. _tutorial:
6-
75
========================
86
Welcome to Sage Tutorial
97
========================

src/sage/interacts/library.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Sage Interacts
33
44
Sage interacts are applications of the `@interact decorator <../../sagenb/notebook/interact.html>`_.
5-
They are conveniently accessible in the Sage Notebook via ``interacts.[TAB].[TAB]()``.
5+
They are conveniently accessible in the Sage notebook via ``interacts.[TAB].[TAB]()``.
66
The first ``[TAB]`` lists categories and the second ``[TAB]`` reveals the interact examples.
77
88
EXAMPLES:

src/sage/misc/cython.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -578,6 +578,9 @@ def cython_import_all(filename, globals, **kwds):
578578
579579
- ``filename`` -- string; name of a file that contains Cython
580580
code
581+
582+
See the function :func:`sage.misc.cython.cython` for documentation
583+
for the other inputs.
581584
"""
582585
m = cython_import(filename, **kwds)
583586
for k, x in m.__dict__.items():
@@ -621,6 +624,9 @@ def compile_and_load(code, **kwds):
621624
- ``code`` -- string containing code that could be in a .pyx file
622625
that is attached or put in a %cython block in the notebook
623626
627+
See the function :func:`sage.misc.cython.cython` for documentation
628+
for the other inputs.
629+
624630
OUTPUT: a module, which results from compiling the given code and
625631
importing it
626632

src/sage/misc/persist.pyx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ def load(*filename, compress=True, verbose=True, **kwargs):
9292
an ``.sobj`` extension added if it doesn't have one. Or, if the input
9393
is a filename ending in ``.py``, ``.pyx``, ``.sage``, ``.spyx``,
9494
``.f``, ``.f90`` or ``.m``, load that file into the current running
95-
session.
95+
session using :func:`sage.repl.load.load`.
9696
9797
Loaded files are not loaded into their own namespace, i.e., this is
9898
much more like Python's ``execfile`` than Python's ``import``.

src/sage/plot/animate.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -839,7 +839,7 @@ def show(self, delay=None, iterations=None, **kwds):
839839
840840
sage: a.show(delay=50) # long time # optional -- ImageMagick
841841
842-
You can also make use of the HTML5 video element in the Sage Notebook::
842+
You can also make use of the HTML5 video element in the Sage notebook::
843843
844844
sage: # long time, optional -- FFmpeg
845845
sage: a.show(format='ogg')

src/sage/repl/attach.py

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -318,8 +318,12 @@ def attach(*files):
318318
319319
.. SEEALSO::
320320
321-
:meth:`~sage.repl.load.load` is the same as :func:`attach`, but
322-
does not automatically reload a file when it changes.
321+
:func:`~sage.repl.load.load` is the same as :func:`attach`, but
322+
does not automatically reload a file when it changes unless
323+
``attach=True`` is passed.
324+
325+
``%attach`` magic can also be used, see
326+
:meth:`~sage.repl.ipython_extension.SageMagics.attach`.
323327
324328
EXAMPLES:
325329

src/sage/repl/ipython_extension.py

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,10 @@ def runfile(self, s):
107107
108108
- ``s`` -- string; the file to be loaded
109109
110+
.. SEEALSO::
111+
112+
This is the same as :func:`~sage.repl.load.load`.
113+
110114
EXAMPLES::
111115
112116
sage: import os
@@ -133,6 +137,10 @@ def attach(self, s):
133137
134138
- ``s`` -- string. The file to be attached
135139
140+
.. SEEALSO::
141+
142+
This is the same as :func:`~sage.repl.attach.attach`.
143+
136144
EXAMPLES::
137145
138146
sage: from sage.repl.interpreter import get_test_shell

src/sage/repl/load.py

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,14 @@ def load(filename, globals, attach=False):
8787
8888
from t import *
8989
90+
.. NOTE::
91+
92+
The global ``load`` function is :func:`sage.misc.persist.load`,
93+
which delegates to this function for code file formats.
94+
95+
``%runfile`` magic can also be used, see
96+
:meth:`~sage.repl.ipython_extension.SageMagics.runfile`.
97+
9098
INPUT:
9199
92100
- ``filename`` -- string (denoting a filename or URL) or a :class:`Path` object
@@ -97,13 +105,15 @@ def load(filename, globals, attach=False):
97105
- ``attach`` -- boolean (default: ``False``); whether to add the
98106
file to the list of attached files
99107
100-
Loading an executable Sage script from the command prompt will run whatever
101-
code is inside an
108+
Loading an executable Sage script from the :ref:`command line <section-command-line>`
109+
will run whatever code is inside an
110+
111+
::
102112
103113
if __name__ == "__main__":
104114
105115
section, as the condition on ``__name__`` will hold true (code run from the
106-
command prompt is considered to be running in the ``__main__`` module.)
116+
command line is considered to be running in the ``__main__`` module.)
107117
108118
EXAMPLES:
109119
@@ -159,7 +169,8 @@ def load(filename, globals, attach=False):
159169
160170
sage: sage.repl.load.load('https://raw.githubusercontent.com/sagemath/sage-patchbot/3.0.0/sage_patchbot/util.py', globals()) # optional - internet
161171
162-
We attach a file::
172+
We attach a file (note that :func:`~sage.repl.attach.attach`
173+
is equivalent, but available at the global scope by default)::
163174
164175
sage: t = tmp_filename(ext='.py')
165176
sage: with open(t, 'w') as f:

0 commit comments

Comments
 (0)