Sphinx Remote Literal Include

sphinxext-remoteliteralinclude

Note

This page was:
Created May 26 2021
Updated May 26 2021
Last Built Tue, 03 Aug 2021 10:25 PM UTC

Homepage

https://github.com/wpilibsuite/sphinxext-remoteliteralinclude

Here is how to call the extension for remote literal include for example.java

.. rli:: https://example.com/example.java
:language: java
:lines: 1-29
:linenos:
:lineno-start: 1

For some reason this does not literal include correctly: https://example.com/example.java

Here is how to call the extension for remote literal include for README.md using line numbers

.. rli:: https://raw.githubusercontent.com/wpilibsuite/sphinxext-remoteliteralinclude/main/README.md
:language: java
:lines: 1-29
:linenos:
:lineno-start: 1

Here is a literal include README.md with shading and line numbers

 1# sphinxext-remoteliteralinclude
 2
 3![CI](https://github.com/wpilibsuite/sphinxext-remoteliteralinclude/workflows/CI/badge.svg)
 4
 5Sphinx extension that extends the ``literalinclude`` directive to allow remote URLS
 6
 7## Installation
 8
 9Please install the extension via pip using the following command:
10
11``python3 -m pip install sphinxext-remoteliteralinclude``
12
13then in your ``conf.py`` under ``extensions``, it should look like the following:
14
15```python
16extensions = ["sphinxext.remoteliteralinclude"]
17```
18
19## Usage
20
21Simply just use it as you normally would a normal ``literalinclude``
22
23```
24.. rli:: https://example.com/example.java
25   :language: java
26   :lines: 10-29
27   :linenos:
28   :lineno-start: 10
29```

Here is how to call the extension for remote literal include for README.md embedded

.. rli:: https://raw.githubusercontent.com/wpilibsuite/sphinxext-remoteliteralinclude/main/README.md

Here is a README.md as if it was typed right into this document

# sphinxext-remoteliteralinclude

![CI](https://github.com/wpilibsuite/sphinxext-remoteliteralinclude/workflows/CI/badge.svg)

Sphinx extension that extends the ``literalinclude`` directive to allow remote URLS

## Installation

Please install the extension via pip using the following command:

``python3 -m pip install sphinxext-remoteliteralinclude``

then in your ``conf.py`` under ``extensions``, it should look like the following:

```python
extensions = ["sphinxext.remoteliteralinclude"]
```

## Usage

Simply just use it as you normally would a normal ``literalinclude``

```
.. rli:: https://example.com/example.java
   :language: java
   :lines: 10-29
   :linenos:
   :lineno-start: 10
```

## Important Notes

This is simply a modification of the normal literalinclude extension. Near all of the code is the exact same. Modifications are made by Eli Barnett, with pip module creation by Dalton Smith. 

Using the extension to reference local files **will not** work. Use the regular ``literalinclude`` extension in that case.

Last change: Tue, 03 Aug 2021 10:25 PM UTC