Skip to content

Removed $ before shell commands in docs #4699

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Removed $ before shell commands in docs #4699

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5c52644
Removed $ before shell commands in docs
Oct 1, 2018
e11a3e4
Hopefully fixed formatting issue
Oct 1, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/api/v2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Project list

.. sourcecode:: bash

$ curl https://readthedocs.org/api/v2/project/?slug=pip
curl https://readthedocs.org/api/v2/project/?slug=pip

**Example response**:

Expand Down Expand Up @@ -234,7 +234,7 @@ Build list

.. sourcecode:: bash

$ curl https://readthedocs.org/api/v2/build/?project__slug=pip
curl https://readthedocs.org/api/v2/build/?project__slug=pip

**Example response**:

Expand Down
12 changes: 6 additions & 6 deletions docs/contribute.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ Contributing to Read the Docs
=============================

You are here to help on Read the Docs? Awesome, feel welcome and read the
following sections in order to know how to ask questions and how to work on something.
following sections in order to know how to ask questions and how to work on something.

All members of our community are expected to follow our :doc:`/code-of-conduct`.
Please make sure you are welcoming and friendly in all of our spaces.
Expand Down Expand Up @@ -51,18 +51,18 @@ 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::

$ pip install -U pre-commit
$ git add <your-modified-files>
$ pre-commit run
pip install -U pre-commit
git add <your-modified-files>
pre-commit run

or to run against a specific file::

$ pre-commit run --files <file.py>
pre-commit run --files <file.py>

`pre-commit` can also be run as a git pre-commit hook. You can set this up
with::

$ 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.
Expand Down
68 changes: 34 additions & 34 deletions docs/custom_installs/local_rtd_vm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,23 @@ Assumptions and Prerequisites
* Debian VM provisioned with python 2.7.x
* 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
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

* Git ::

$ sudo apt-get install git
sudo apt-get install git
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And here


* Git repo is ``git.corp.company.com:git/docs/documentation.git``
* Source documents are in ``../docs/source``
* Sphinx ::

$ sudo pip install sphinx
sudo pip install sphinx
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The same problem occurs here


.. note:: Not using sudo may prevent access. “error: could not create '/usr/local/lib/python2.7/dist-packages/markupsafe': Permission denied”
.. note:: Not using sudo may prevent access. “error: could not create '/usr/local/lib/python2.7/dist-packages/markupsafe': Permission denied”

Local RTD Setup
---------------
Expand All @@ -33,40 +33,40 @@ Install RTD

To host your documentation on a local RTD installation, set it up in your VM. ::

$ 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. ::

$ 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
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-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 ::

$ sudo pip install -r requirements.txt
sudo pip install -r requirements.txt

Configure the RTD Server and Superuser
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Run the following commands. ::

$ ./manage.py migrate
$ ./manage.py createsuperuser
./manage.py migrate
./manage.py createsuperuser

2. This will prompt you to create a superuser account for Django. Enter appropriate details. For example: ::

Expand All @@ -79,8 +79,8 @@ RTD Server Administration

Navigate to the ``../checkouts/readthedocs.org`` folder in your VM and run the following command. ::

$ ./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.

Expand All @@ -92,7 +92,7 @@ Go to the dashboard at ``http://[VM IP ADDRESS]:8000/dashboard`` and follow the
3. Navigate to the root path for documentation.
4. Run the following Sphinx commands. ::

$ 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``

Expand All @@ -107,29 +107,29 @@ Possible Error and Resolution

1. In your machine, navigate to the ``.ssh`` folder. ::

$ cd .ssh/
$ cat id_rsa
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. ::

$ 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**
**Workaround 2**

SSH to the VM using the ``-A`` directive. ::

$ ssh document-vm -A
ssh document-vm -A

This provides all permissions for that particular remote session, which are revoked when you logout.

Build Documentation on Local RTD Instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Log into ``http://[VM IP ADDRESS]:[PORT]`` using the django superuser creds and follow these steps.
Log into ``http://[VM IP ADDRESS]:[PORT]`` using the django superuser creds and follow these steps.

For a new project
`````````````````
Expand Down
14 changes: 7 additions & 7 deletions docs/getting_started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,17 +24,17 @@ There is `a screencast`_ that will help you get started if you prefer.
Sphinx_ is a tool that makes it easy to create beautiful documentation.
Assuming you have Python_ already, `install Sphinx`_::

$ pip install sphinx sphinx-autobuild
pip install sphinx sphinx-autobuild

Create a directory inside your project to hold your docs::

$ cd /path/to/project
$ mkdir docs
cd /path/to/project
mkdir docs

Run ``sphinx-quickstart`` in there::

$ cd docs
$ sphinx-quickstart
cd docs
sphinx-quickstart

This quick start will walk you through creating the basic configuration; in most cases, you
can just accept the defaults. When it's done, you'll have an ``index.rst``, a
Expand All @@ -44,7 +44,7 @@ Now, edit your ``index.rst`` and add some information about your project.
Include as much detail as you like (refer to the reStructuredText_ syntax
or `this template`_ if you need help). Build them to see how they look::

$ make html
make html

.. note:: You can use ``sphinx-autobuild`` to auto-reload your docs. Run ``sphinx-autobuild . _build/html`` instead.

Expand All @@ -57,7 +57,7 @@ In Markdown
You can use Markdown and reStructuredText in the same Sphinx project.
We support this natively on Read the Docs, and you can do it locally::

$ pip install recommonmark
pip install recommonmark

Then in your ``conf.py``:

Expand Down
32 changes: 16 additions & 16 deletions docs/guides/manage-translations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ To generate these ``.pot`` files it's needed to run this command from your ``doc

.. code-block:: console

$ sphinx-build -b gettext . _build/gettext
sphinx-build -b gettext . _build/gettext


.. tip::
Expand All @@ -59,7 +59,7 @@ First, you need to install it:

.. code-block:: console

$ pip install sphinx-intl
pip install sphinx-intl


As a second step, we want to create a directory with each translated file per target language
Expand All @@ -68,7 +68,7 @@ This can be achieved with the following command:

.. code-block:: console

$ sphinx-intl update -p _build/gettext -l es_AR -l pt_BR
sphinx-intl update -p _build/gettext -l es_AR -l pt_BR

This command will create a directory structure similar to the following
(with one ``.po`` file per ``.rst`` file in your documentation)::
Expand Down Expand Up @@ -115,7 +115,7 @@ To do this, run this command:

.. code-block:: console

$ pip install transifex-client
pip install transifex-client

After installing it, you need to configure your account.
For this, you need to create an API Token for your user to access this service through the command line.
Expand All @@ -128,15 +128,15 @@ Now, you need to setup it to use this token:

.. code-block:: console

$ tx init --token $TOKEN --no-interactive
tx init --token $TOKEN --no-interactive


The next step is to map every ``.pot`` file you have created in the previous step to a resource under Transifex.
To achieve this, you need to run this command:

.. code-block:: console

$ tx config mapping-bulk \
tx config mapping-bulk \
--project $TRANSIFEX_PROJECT \
--file-extension '.pot' \
--source-file-dir docs/_build/gettext \
Expand All @@ -152,15 +152,15 @@ To do this, you can run this command:

.. code-block:: console

$ tx push --source
tx push --source


Now, you can go to your Transifex's project and check that there is one resource per ``.rst`` file of your documentation.
After the source files are translated using Transifex, you can download all the translations for all the languages by running:

.. code-block:: console

$ tx pull --all
tx pull --all

This command will leave the ``.po`` files needed for building the documentation in the target language under ``locale/<lang>/LC_MESSAGES``.

Expand All @@ -178,7 +178,7 @@ Finally, to build our documentation in Spanish(Argentina) we need to tell Sphinx

.. code-block:: console

$ sphinx-build -b html -D language=es_AR . _build/html/es_AR
sphinx-build -b html -D language=es_AR . _build/html/es_AR

.. note::

Expand All @@ -199,19 +199,19 @@ Once you have done changes in your documentation, you may want to make these add

.. code-block:: console

$ sphinx-build -b gettext . _build/gettext
sphinx-build -b gettext . _build/gettext


.. For the manual workflow, we need to run this command

$ sphinx-intl update -p _build/gettext -l es_AR -l pt_BR
sphinx-intl update -p _build/gettext -l es_AR -l pt_BR


#. Push new files to Transifex

.. code-block:: console

$ tx push --sources
tx push --sources


Build documentation from up to date translation
Expand All @@ -223,14 +223,14 @@ When translators have finished their job, you may want to update the documentati

.. code-block:: console

$ tx pull --all
tx pull --all

#. Commit and push these changes to our repo

.. code-block:: console

$ git add locale/
$ git commit -m "Update translations"
$ git push
git add locale/
git commit -m "Update translations"
git push

The last ``git push`` will trigger a build per translation defined as part of your project under Read the Docs and make it immediately available.
6 changes: 3 additions & 3 deletions docs/i18n.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,7 @@ performance. To compile the latest PO files in the repository, Django provides
the ``compilemessages`` management command. For example, to compile all the
available localizations, just run::

$ python manage.py compilemessages -a
python manage.py compilemessages -a

You will need to do this every time you want to push updated translations to
the live site.
Expand Down Expand Up @@ -306,10 +306,10 @@ help pages <http://help.transifex.com/features/client/>`_.

.. code-block:: console

$ fab i18n_push_source
fab i18n_push_source

#. Pull changes (new translations) from Transifex:

.. code-block:: console

$ fab i18n_pull
fab i18n_pull
Loading