Skip to content

Commit 38cb8c5

Browse files
AA-TurnerAA-Turner
committed
Move most README content to the documentation
1 parent abacb67 commit 38cb8c5

File tree

4 files changed

+216
-166
lines changed

4 files changed

+216
-166
lines changed

‎README.rst‎

Lines changed: 2 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -42,167 +42,6 @@ Installation
4242
Usage
4343
=====
4444

45-
Just add ``sphinxext.rediraffe`` to the extensions list in ``conf.py``
45+
See the `documentation`_.
4646

47-
.. code-block:: python
48-
49-
extensions = [
50-
'sphinxext.rediraffe',
51-
]
52-
53-
Set ``rediraffe_redirects`` to a dict or file of redirects in your :file:`conf.py`.
54-
55-
Diff Checker
56-
------------
57-
58-
The diff checker ensures that deleted or renamed files in your git repo
59-
are in your redirects.
60-
61-
To run the diff checker:
62-
63-
1. Set ``rediraffe_branch`` and ``rediraffe_redirects`` in conf.py.
64-
2. Run the ``rediraffecheckdiff`` builder.
65-
66-
Auto Redirect builder
67-
---------------------
68-
69-
The auto redirect builder can be used to automatically add renamed files
70-
to your redirects file.
71-
Simply run the ``rediraffewritediff`` builder.
72-
73-
To run the auto redirecter:
74-
75-
1. Set ``rediraffe_branch`` and ``rediraffe_redirects`` in conf.py.
76-
2. Run the ``rediraffewritediff`` builder.
77-
78-
Note: The auto redirect builder only works with a configuration file.
79-
80-
Note: Deleted files cannot be added to your redirects file automatically.
81-
82-
83-
Options
84-
=======
85-
86-
These values are placed in the :file:`conf.py` of your Sphinx project.
87-
88-
``rediraffe_branch``
89-
**Required** for the ``rediraffecheckdiff`` and ``rediraffewritediff`` builders.
90-
The branch or commit to diff against.
91-
92-
``rediraffe_redirects``
93-
**Required.**
94-
A filename or dict containing redirects.
95-
96-
``rediraffe_template``
97-
**Optional.**
98-
A jinja template to use to render the inserted redirecting files.
99-
If not specified, a default template will be used.
100-
This template will only be accessed after the html/htmldir builder is finished;
101-
Therefore, this file may be generated as part of your build.
102-
103-
Variables available to ``rediraffe_template``:
104-
105-
* ``from_file`` - the file being redirected as written in ``rediraffe_redirects``.
106-
* ``to_file`` - the destination file that from_file is redirected to
107-
as written in ``rediraffe_redirects``.
108-
* ``from_url`` - the path to ``from_url``'s html file (built by rediraffe)
109-
relative to the outdir.
110-
* ``to_url`` - the path to ``to_url``'s built html file relative to the outdir.
111-
* ``rel_url`` - the relative path from ``from_url`` to ``to_url``.
112-
113-
``rediraffe_auto_redirect_perc``
114-
**Optional.**
115-
Only used by the ``rediraffewritediff`` builder.
116-
The percentage as an integer representing the accuracy required before
117-
auto redirecting with the ``rediraffewritediff`` builder.
118-
The default is 100.
119-
120-
Example Config
121-
==============
122-
123-
redirects only (file)
124-
---------------------
125-
126-
conf.py:
127-
128-
.. code-block:: python
129-
130-
rediraffe_redirects = "redirects.txt"
131-
132-
redirects.txt:
133-
134-
.. code-block:: text
135-
136-
# comments start with "#"
137-
"another file.rst" index.rst
138-
another2.rst 'another file.rst'
139-
140-
Note: Filepaths can be wrapped in quotes (single or double).
141-
This is especially useful for filepaths containing spaces.
142-
143-
redirects only (dict)
144-
---------------------
145-
146-
conf.py:
147-
148-
.. code-block:: python
149-
150-
rediraffe_redirects = {
151-
"another.rst": "index.rst",
152-
"another2.rst": "another.rst",
153-
}
154-
155-
redirects + diff checker
156-
------------------------
157-
158-
conf.py:
159-
160-
.. code-block:: python
161-
162-
rediraffe_redirects = "redirects.txt"
163-
rediraffe_branch = "main~1"
164-
165-
redirects with jinja template
166-
-----------------------------
167-
168-
conf.py:
169-
170-
.. code-block:: python
171-
172-
rediraffe_redirects = "redirects.txt"
173-
rediraffe_template = "template.html"
174-
175-
176-
template.html:
177-
178-
.. code-block:: html
179-
180-
<html>
181-
<body>
182-
<p>Your destination is {{to_url}}</p>
183-
</body>
184-
</html>
185-
186-
A complex example can be found at tests/roots/ext/.
187-
188-
Testing
189-
=======
190-
191-
Rediraffe uses pytest for testing.
192-
To run tests:
193-
194-
1. Install this package
195-
2. Install test dependencies
196-
197-
.. code-block:: sh
198-
199-
python -m pip install --group test
200-
201-
3. Navigate to the tests directory and run
202-
203-
.. code-block:: sh
204-
205-
python -m pytest --headless
206-
207-
The ``--headless`` flag ensures that a browser window does not open
208-
during browser backed selenium testing.
47+
.. _documentation: https://sphinxext-rediraffe.readthedocs.io/en/latest/

‎docs/conf.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,14 @@
1414
html_logo = '../assets/rediraffe_logo_128.png'
1515

1616
extensions = [
17+
'sphinx.ext.intersphinx',
1718
'sphinxext.rediraffe',
1819
]
1920

21+
intersphinx_mapping = {
22+
'sphinx': ('https://www.sphinx-doc.org/', None),
23+
}
24+
2025
rediraffe_redirects = {
2126
'other.rst': 'index.rst',
2227
'other2.rst': 'other.rst',

‎docs/index.rst‎

Lines changed: 207 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,207 @@
1-
.. include:: ../README.rst
1+
===================
2+
sphinxext-rediraffe
3+
===================
4+
5+
.. role:: code-py(code)
6+
:language: Python
7+
8+
This Sphinx extension redirects non-existent pages to working pages.
9+
Rediraffe can also check that deleted or renamed files in your git repo
10+
are redirected.
11+
12+
Rediraffe creates a graph of all specified redirects and traverses it
13+
to point all internal urls to leaf urls.
14+
This means that chained redirects will be resolved.
15+
For example, if a config has 6 chained redirects, all 6 links will redirect
16+
directly to the final link.
17+
The end user will never experience more than 1 redirection.
18+
19+
Note: Rediraffe supports the html and dirhtml builders.
20+
21+
Installation
22+
============
23+
24+
.. code-block:: sh
25+
26+
python -m pip install sphinxext-rediraffe
27+
28+
Usage
29+
=====
30+
31+
Just add ``sphinxext.rediraffe`` to the extensions list in :file:`conf.py`,
32+
33+
.. code-block:: python
34+
35+
extensions = [
36+
'sphinxext.rediraffe',
37+
]
38+
39+
and set :confval:`rediraffe_redirects` to a dict or file of redirects.
40+
41+
Diff Checker
42+
------------
43+
44+
The diff checker ensures that deleted or renamed files in your git repo
45+
are in your redirects.
46+
47+
To run the diff checker:
48+
49+
1. Set :confval:`rediraffe_branch` and :confval:`rediraffe_redirects`
50+
in :file:`conf.py`.
51+
2. Run the ``rediraffecheckdiff`` builder.
52+
53+
Auto Redirect builder
54+
---------------------
55+
56+
The auto redirect builder can be used to automatically add renamed files
57+
to your redirects file.
58+
Simply run the ``rediraffewritediff`` builder.
59+
60+
To run the auto redirecter:
61+
62+
1. Set :confval:`rediraffe_branch` and :confval:`rediraffe_redirects`
63+
in :file:`conf.py`.
64+
2. Run the ``rediraffewritediff`` builder.
65+
66+
Note: The auto redirect builder only works with a configuration file.
67+
68+
Note: Deleted files cannot be added to your redirects file automatically.
69+
70+
71+
Options
72+
=======
73+
74+
These values are placed in the :file:`conf.py` of your Sphinx project.
75+
76+
.. confval:: rediraffe_branch
77+
:type: :code-py:`str`
78+
:default: :code-py:`''`
79+
80+
**Required** for the ``rediraffecheckdiff`` & ``rediraffewritediff`` builders.
81+
The branch or commit to diff against.
82+
83+
.. confval:: rediraffe_redirects
84+
:type: :code-py:`str | dict[str, str]`
85+
86+
A filename or dict containing redirects.
87+
88+
.. confval:: rediraffe_template
89+
:type: :code-py:`str`
90+
:default: :code-py:`None`
91+
92+
A jinja template to use to render the inserted redirecting files.
93+
If not specified, a default template will be used.
94+
This template will only be accessed after the html/htmldir builder is finished,
95+
meaning that this file may be generated as part of your build.
96+
97+
Variables available to :confval:`!rediraffe_template`:
98+
99+
``from_file``
100+
the file being redirected as written in :confval:`rediraffe_redirects`.
101+
``to_file``
102+
the destination file that from_file is redirected to as written in
103+
:confval:`rediraffe_redirects`.
104+
``from_url``
105+
the path to ``from_url``'s html file (built by rediraffe) relative to the
106+
:confval:`!outdir`.
107+
``to_url``
108+
the path to ``to_url``'s built html file relative to the :confval:`!outdir`.
109+
``rel_url``
110+
the relative path from ``from_url`` to ``to_url``.
111+
112+
.. confval:: rediraffe_auto_redirect_perc
113+
:type: :code-py:`int`
114+
:default: :code-py:`100`
115+
116+
Only used by the ``rediraffewritediff`` builder.
117+
The percentage as an integer representing the accuracy required before
118+
auto redirecting with the ``rediraffewritediff`` builder.
119+
120+
Example Config
121+
==============
122+
123+
redirects only (file)
124+
---------------------
125+
126+
:file:`conf.py`:
127+
128+
.. code-block:: python
129+
130+
rediraffe_redirects = 'redirects.txt'
131+
132+
:file:`redirects.txt`:
133+
134+
.. code-block:: text
135+
136+
# comments start with '#'
137+
'another file.rst' index.rst
138+
another2.rst "another file.rst"
139+
140+
Note: Filepaths can be wrapped in quotes (single or double).
141+
This is especially useful for filepaths containing spaces.
142+
143+
redirects only (dict)
144+
---------------------
145+
146+
:file:`conf.py`:
147+
148+
.. code-block:: python
149+
150+
rediraffe_redirects = {
151+
'another.rst': 'index.rst',
152+
'another2.rst': 'another.rst',
153+
}
154+
155+
redirects + diff checker
156+
------------------------
157+
158+
:file:`conf.py`:
159+
160+
.. code-block:: python
161+
162+
rediraffe_redirects = 'redirects.txt'
163+
rediraffe_branch = 'main~1'
164+
165+
redirects with jinja template
166+
-----------------------------
167+
168+
:file:`conf.py`:
169+
170+
.. code-block:: python
171+
172+
rediraffe_redirects = 'redirects.txt'
173+
rediraffe_template = 'template.html'
174+
175+
:file:`template.html`:
176+
177+
.. code-block:: html
178+
179+
<html>
180+
<body>
181+
<p>Your destination is {{to_url}}</p>
182+
</body>
183+
</html>
184+
185+
A complex example can be found at :file:`tests/roots/ext/`.
186+
187+
Testing
188+
=======
189+
190+
Rediraffe uses pytest for testing.
191+
To run tests:
192+
193+
1. Install this package
194+
2. Install test dependencies
195+
196+
.. code-block:: sh
197+
198+
python -m pip install --group test
199+
200+
3. Navigate to the tests directory and run
201+
202+
.. code-block:: sh
203+
204+
python -m pytest --headless
205+
206+
The ``--headless`` flag ensures that a browser window does not open
207+
during browser backed selenium testing.

0 commit comments

Comments
 (0)