Merge pull request #4990 from dojutsu-user/use-sphinx-prompt

Make $ unselectable in docs
readthedocs · Jan 10, 2019 · dde80f8 · dde80f8
2 parents 05a2a4e + e06869e
commit dde80f8
Show file tree

Hide file tree

Showing 13 changed files with 210 additions and 135 deletions.
diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg
@@ -1,4 +1,4 @@
 [rstcheck]
-ignore_directives=automodule,http:get,tabs,tab
+ignore_directives=automodule,http:get,tabs,tab,prompt
 ignore_roles=djangosetting,setting
 ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced)
diff --git a/docs/_static/css/sphinx_prompt_css.css b/docs/_static/css/sphinx_prompt_css.css
@@ -0,0 +1,13 @@
+/* CSS for sphinx-prompt */
+
+pre.highlight {
+  border: 1px solid #e1e4e5;
+  overflow-x: auto;
+  margin: 1px 0 24px 0;
+  padding: 12px 12px;
+}
+
+pre.highlight span.prompt1 {
+  font-size: 12px;
+  line-height: 1.4;
+}
diff --git a/docs/api/v2.rst b/docs/api/v2.rst
@@ -53,9 +53,9 @@ Project list
 
     **Example request**:
 
-    .. sourcecode:: bash
+    .. prompt:: bash $
 
-        $ curl https://readthedocs.org/api/v2/project/?slug=pip
+        curl https://readthedocs.org/api/v2/project/?slug=pip
 
     **Example response**:
 
@@ -232,9 +232,9 @@ Build list
 
     **Example request**:
 
-    .. sourcecode:: bash
+    .. prompt:: bash $
 
-        $ curl https://readthedocs.org/api/v2/build/?project__slug=pip
+        curl https://readthedocs.org/api/v2/build/?project__slug=pip
 
     **Example response**:
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -28,6 +28,7 @@
     'djangodocs',
     'doc_extensions',
     'sphinx_tabs.tabs',
+    'sphinx-prompt',
 ]
 templates_path = ['_templates']
 
@@ -82,3 +83,7 @@
 
 # Activate autosectionlabel plugin
 autosectionlabel_prefix_document = True
+
+
+def setup(app):
+    app.add_stylesheet('css/sphinx_prompt_css.css')
diff --git a/docs/contribute.rst b/docs/contribute.rst
@@ -49,20 +49,26 @@ install `pre-commit`_ and it will automatically run different linting tools
 and `yapf`_) to check your changes before you commit them. `pre-commit` will let
 you know if there were any problems that is wasn't able to fix automatically.
 
-To run the `pre-commit` command and check your changes::
+To run the `pre-commit` command and check your changes:
 
-    $ pip install -U pre-commit
-    $ git add <your-modified-files>
-    $ pre-commit run
+.. prompt:: bash $
 
-or to run against a specific file::
+    pip install -U pre-commit
+    git add <your-modified-files>
+    pre-commit run
 
-    $ pre-commit run --files <file.py>
+or to run against a specific file:
+
+.. prompt:: bash $
+
+    pre-commit run --files <file.py>
 
 `pre-commit` can also be run as a git pre-commit hook. You can set this up
-with::
+with:
+
+.. prompt:: bash $
 
-    $ pre-commit install
+    pre-commit install
 
 After this installation, the next time you run `git commit` the `pre-commit run`
 command will be run immediately and will inform you of the changes and errors.

diff --git a/docs/custom_installs/elasticsearch.rst b/docs/custom_installs/elasticsearch.rst
@@ -12,9 +12,11 @@ Installing Java
 Elasticsearch requires Java 8 or later. Use `Oracle official documentation <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_. 
 or opensource distribution like `OpenJDK <http://openjdk.java.net/install/>`_.
 
-After installing java, verify the installation by,::
+After installing java, verify the installation by,:
 
-    $ java -version
+.. prompt:: bash $
+
+    java -version
 
 The result should be something like this::
 
@@ -31,52 +33,68 @@ Elasticsearch can be downloaded directly from elastic.co. For Ubuntu, it's best
 RTD currently uses elasticsearch 1.x which can be easily downloaded and installed from `elastic.co 
 <https://www.elastic.co/downloads/past-releases/elasticsearch-1-3-8/>`_.
 
-Install the downloaded package by following command::
+Install the downloaded package by following command:
+
+.. prompt:: bash $
 
-    $ sudo apt install .{path-to-downloaded-file}/elasticsearch-1.3.8.deb
+    sudo apt install .{path-to-downloaded-file}/elasticsearch-1.3.8.deb
 
 Custom setup
 ------------
 
-You need the icu plugin::
+You need the icu plugin:
+
+.. prompt:: bash $
 
-    $ elasticsearch/bin/plugin -install elasticsearch/elasticsearch-analysis-icu/2.3.0
+    elasticsearch/bin/plugin -install elasticsearch/elasticsearch-analysis-icu/2.3.0
 
 Running Elasticsearch from command line
 ---------------------------------------
 
-Elasticsearch is not started automatically after installation. How to start and stop Elasticsearch depends on whether your system uses SysV init or systemd (used by newer distributions). You can tell which is being used by running this command::
+Elasticsearch is not started automatically after installation. How to start and stop Elasticsearch depends on whether your system uses SysV init or systemd (used by newer distributions). You can tell which is being used by running this command:
 
-    $ ps -p 1   
+.. prompt:: bash $
+
+    ps -p 1   
 
 **Running Elasticsearch with SysV init**
 
-Use the ``update-rc.d command`` to configure Elasticsearch to start automatically when the system boots up::
+Use the ``update-rc.d command`` to configure Elasticsearch to start automatically when the system boots up:
+
+.. prompt:: bash $
+
+    sudo update-rc.d elasticsearch defaults 95 10
 
-    $ sudo update-rc.d elasticsearch defaults 95 10
+Elasticsearch can be started and stopped using the service command:
 
-Elasticsearch can be started and stopped using the service command::
+.. prompt:: bash $
 
-    $ sudo -i service elasticsearch start
-    $ sudo -i service elasticsearch stop
+    sudo -i service elasticsearch start
+    sudo -i service elasticsearch stop
 
 If Elasticsearch fails to start for any reason, it will print the reason for failure to STDOUT. Log files can be found in /var/log/elasticsearch/.
 
 **Running Elasticsearch with systemd**
 
-To configure Elasticsearch to start automatically when the system boots up, run the following commands::
+To configure Elasticsearch to start automatically when the system boots up, run the following commands:
 
-    $ sudo /bin/systemctl daemon-reload
-    $ sudo /bin/systemctl enable elasticsearch.service
+.. prompt:: bash $
 
-Elasticsearch can be started and stopped as follows::
+    sudo /bin/systemctl daemon-reload
+    sudo /bin/systemctl enable elasticsearch.service
 
-    $ sudo systemctl start elasticsearch.service
-    $ sudo systemctl stop elasticsearch.service
+Elasticsearch can be started and stopped as follows:
 
-To verify run::
+.. prompt:: bash $
 
-    $ curl http://localhost:9200
+    sudo systemctl start elasticsearch.service
+    sudo systemctl stop elasticsearch.service
+
+To verify run:
+
+.. prompt:: bash $
+
+    curl http://localhost:9200
 
 
 You should get something like::
@@ -97,12 +115,16 @@ You should get something like::
 Index the data available at RTD database
 ----------------------------------------
 
-You need to create the indexes::
+You need to create the indexes:
+
+.. prompt:: bash $
+
+    python manage.py provision_elasticsearch
 
-    $ python manage.py provision_elasticsearch
+In order to search through the RTD database, you need to index it into the elasticsearch index:
 
-In order to search through the RTD database, you need to index it into the elasticsearch index:: 
+.. prompt:: bash $ 
 
-    $ python manage.py reindex_elasticsearch
+    python manage.py reindex_elasticsearch
 
 You are ready to go!
diff --git a/docs/custom_installs/local_rtd_vm.rst b/docs/custom_installs/local_rtd_vm.rst
@@ -5,23 +5,29 @@ Assumptions and Prerequisites
 -----------------------------
 
 * Debian VM provisioned with python 2.7.x
-* All python dependencies and setup tools are installed ::
+* All python dependencies and setup tools are installed:
 
-  $ sudo apt-get install python-setuptools
-  $ sudo apt-get install build-essential
-  $ sudo apt-get install python-dev
-  $ sudo apt-get install libevent-dev
-  $ sudo easy_install pip 
+.. prompt:: bash $
 
-* Git ::
+  sudo apt-get install python-setuptools
+  sudo apt-get install build-essential
+  sudo apt-get install python-dev
+  sudo apt-get install libevent-dev
+  sudo easy_install pip 
 
-  $ sudo apt-get install git
+* Git:
+
+.. prompt:: bash $
+
+  sudo apt-get install git
 
 * Git repo is ``git.corp.company.com:git/docs/documentation.git``
 * Source documents are in ``../docs/source``
-* Sphinx ::
+* Sphinx:
 
-  $ sudo pip install sphinx
+.. prompt:: bash $
+
+  sudo pip install sphinx
 
 .. note:: Not using sudo may prevent access. “error: could not create '/usr/local/lib/python2.7/dist-packages/markupsafe': Permission denied” 
 
@@ -31,42 +37,52 @@ Local RTD Setup
 Install RTD
 ~~~~~~~~~~~
 
-To host your documentation on a local RTD installation, set it up in your VM. ::
+To host your documentation on a local RTD installation, set it up in your VM:
+
+.. prompt:: bash $
 
-    $ mkdir checkouts
-    $ cd checkouts
-    $ git clone https://github.com/rtfd/readthedocs.org.git
-    $ cd readthedocs.org
-    $ sudo pip install -r requirements.txt
+    mkdir checkouts
+    cd checkouts
+    git clone https://github.com/rtfd/readthedocs.org.git
+    cd readthedocs.org
+    sudo pip install -r requirements.txt
 
 Possible Error and Resolution
 `````````````````````````````
 
 **Error**: ``error: command 'gcc' failed with exit status 1``
 
-**Resolution**: Run the following commands. ::
+**Resolution**: Run the following commands:
+
+.. prompt:: bash $
+
+    sudo apt-get update
+    sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev libxml2-devel libxslt-devel
+    sudo apt-get build-dep python-imaging --fix-missing 
+
+On Debian 8 (jessie) the command is slightly different:
 
-    $ sudo apt-get update
-    $ sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev libxml2-devel libxslt-devel
-    $ sudo apt-get build-dep python-imaging --fix-missing 
+.. prompt:: bash $
 
-On Debian 8 (jessie) the command is slightly different ::
+    sudo apt-get update
+    sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev libxml2-dev libxslt-dev
+    sudo apt-get build-dep python-imaging --fix-missing 
 
-    $ sudo apt-get update
-    $ sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev libxml2-dev libxslt-dev
-    $ sudo apt-get build-dep python-imaging --fix-missing 
+Also don't forget to re-run the dependency installation
 
-Also don't forget to re-run the dependency installation ::
+.. prompt:: bash $
 
-    $ sudo pip install -r requirements.txt
+    sudo pip install -r requirements.txt
 
 Configure the RTD Server and Superuser
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. Run the following commands. ::
+1. Run the following commands:
 
-    $ ./manage.py migrate
-    $ ./manage.py createsuperuser
+    .. prompt:: bash $
+
+        ./manage.py migrate
+        ./manage.py createsuperuser
 
 2. This will prompt you to create a superuser account for Django. Enter appropriate details. For example: ::
 
@@ -77,10 +93,12 @@ Configure the RTD Server and Superuser
 RTD Server Administration
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Navigate to the ``../checkouts/readthedocs.org`` folder in your VM and run the following command. ::
+Navigate to the ``../checkouts/readthedocs.org`` folder in your VM and run the following command:
+
+.. prompt:: bash $
 
-    $ ./manage.py runserver [VM IP ADDRESS]:8000
-    $ curl -i http://[VM IP ADDRESS]:8000
+    ./manage.py runserver [VM IP ADDRESS]:8000
+    curl -i http://[VM IP ADDRESS]:8000
 
 You should now be able to log into the admin interface from any PC in your LAN at ``http://[VM IP ADDRESS]:8000/admin`` using the superuser account created in django.
 
@@ -90,9 +108,11 @@ Go to the dashboard at  ``http://[VM IP ADDRESS]:8000/dashboard`` and follow the
    Example: ``git.corp.company.com:/git/docs/documentation.git``.
 2. Clone the documentation sources from Git in the VM.
 3. Navigate to the root path for documentation.
-4. Run the following Sphinx commands. ::
+4. Run the following Sphinx commands:
+
+.. prompt:: bash $
 
-    $ make html
+    make html
 
 This generates the HTML documentation site using the default Sphinx theme. Verify the output in your local documentation folder under ``../build/html``
 
@@ -105,24 +125,30 @@ Possible Error and Resolution
 
 **Workaround-1**
 
-1. In your machine, navigate to the ``.ssh`` folder. ::
+1. In your machine, navigate to the ``.ssh`` folder:
 
-    $ cd .ssh/ 
-    $ cat id_rsa 
+    .. prompt:: bash $
+
+        cd .ssh/ 
+        cat id_rsa 
 
 2. Copy the entire Private Key.
 3. Now, SSH to the VM.
-4. Open the ``id_rsa`` file in the VM. ::
+4. Open the ``id_rsa`` file in the VM:
+
+.. prompt:: bash $
 
-    $ vim /home/<username>/.ssh/id_rsa
+    vim /home/<username>/.ssh/id_rsa
 
 5. Paste the RSA key copied from your machine and save file (``Esc``. ``:wq!``).
 
 **Workaround 2** 
 
-SSH to the VM using the ``-A`` directive. ::
+SSH to the VM using the ``-A`` directive:
+
+.. prompt:: bash $
 
-    $ ssh document-vm -A 
+    ssh document-vm -A 
 
 This provides all permissions for that particular remote session, which are revoked when you logout.