From 0777d50f4c954c98213bcaa5db62e50551c8a17c Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Wed, 12 Dec 2018 02:01:19 +0530 Subject: [PATCH 01/13] modify first page --- docs/conf.py | 1 + docs/intro/getting-started-with-sphinx.rst | 10 +++++----- requirements/pip.txt | 1 + 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d5ddc85ad50..9248bb8f5b0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,6 +28,7 @@ 'djangodocs', 'doc_extensions', 'sphinx_tabs.tabs', + 'sphinx-prompt', ] templates_path = ['_templates'] diff --git a/docs/intro/getting-started-with-sphinx.rst b/docs/intro/getting-started-with-sphinx.rst index 4f967c70263..030d9e4d007 100644 --- a/docs/intro/getting-started-with-sphinx.rst +++ b/docs/intro/getting-started-with-sphinx.rst @@ -33,20 +33,20 @@ Quick start Assuming you have Python already, `install Sphinx`_: -.. sourcecode:: bash +.. prompt:: bash $ $ pip install sphinx Create a directory inside your project to hold your docs: -.. sourcecode:: bash +.. prompt:: bash $ $ cd /path/to/project $ mkdir docs Run ``sphinx-quickstart`` in there: -.. sourcecode:: bash +.. prompt:: bash $ $ cd docs $ sphinx-quickstart @@ -59,7 +59,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: -.. sourcecode:: bash +.. prompt:: bash $ $ make html @@ -88,7 +88,7 @@ Using Markdown with Sphinx 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: -.. sourcecode:: bash +.. prompt:: bash $ $ pip install recommonmark diff --git a/requirements/pip.txt b/requirements/pip.txt index 3490128e231..77172ed2e44 100644 --- a/requirements/pip.txt +++ b/requirements/pip.txt @@ -98,6 +98,7 @@ dj-pagination==2.4.0 # Docs sphinxcontrib-httpdomain==1.7.0 +sphinx-prompt==1.0.0 # commonmark 0.5.5 is the latest version compatible with our docs, the # newer ones make `tox -e docs` to fail From e0a51c714ae87b436434e16b09c2f135a3d66289 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Wed, 12 Dec 2018 02:08:07 +0530 Subject: [PATCH 02/13] remove sphinx-prompt --- docs/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 9248bb8f5b0..d5ddc85ad50 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,7 +28,6 @@ 'djangodocs', 'doc_extensions', 'sphinx_tabs.tabs', - 'sphinx-prompt', ] templates_path = ['_templates'] From 90309fe6000dc2ce3795088593305be5a41623fa Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Wed, 12 Dec 2018 02:17:55 +0530 Subject: [PATCH 03/13] add sphinx-prompt to extensions --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index d5ddc85ad50..9248bb8f5b0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,6 +28,7 @@ 'djangodocs', 'doc_extensions', 'sphinx_tabs.tabs', + 'sphinx-prompt', ] templates_path = ['_templates'] From 4aaeb73e3857cc865c9adc8022bd52c5bca5a1e0 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Wed, 12 Dec 2018 14:39:42 +0530 Subject: [PATCH 04/13] update docs till manage-translations --- docs/guides/manage-translations.rst | 62 +++++++++++----------- docs/intro/getting-started-with-mkdocs.rst | 12 ++--- docs/yaml-config.rst | 4 +- 3 files changed, 40 insertions(+), 38 deletions(-) diff --git a/docs/guides/manage-translations.rst b/docs/guides/manage-translations.rst index b651ae0415f..8b79873c007 100644 --- a/docs/guides/manage-translations.rst +++ b/docs/guides/manage-translations.rst @@ -31,9 +31,9 @@ Create translatable files To generate these ``.pot`` files it's needed to run this command from your ``docs/`` directory: -.. code-block:: console +.. prompt:: bash $ - $ sphinx-build -b gettext . _build/gettext + sphinx-build -b gettext . _build/gettext .. tip:: @@ -57,18 +57,18 @@ We recommend using `sphinx-intl`_ tool for this workflow. First, you need to install it: -.. code-block:: console +.. prompt:: bash $ - $ 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 (in this example we are using Spanish/Argentina and Portuguese/Brazil). This can be achieved with the following command: -.. code-block:: console +.. prompt:: bash $ - $ 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):: @@ -113,9 +113,9 @@ To do this, run this command: .. _transifex-client: https://docs.transifex.com/client/introduction -.. code-block:: console +.. prompt:: bash $ - $ 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. @@ -126,17 +126,17 @@ This can be done under your `User's Settings`_. Now, you need to setup it to use this token: -.. code-block:: console +.. prompt:: bash $ - $ 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 +.. prompt:: bash $ - $ tx config mapping-bulk \ + tx config mapping-bulk \ --project $TRANSIFEX_PROJECT \ --file-extension '.pot' \ --source-file-dir docs/_build/gettext \ @@ -150,17 +150,17 @@ This command will generate a file at ``.tx/config`` with all the information nee Finally, you need to upload these files to Transifex platform so translators can start their work. To do this, you can run this command: -.. code-block:: console +.. prompt:: bash $ - $ 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 +.. prompt:: bash $ - $ tx pull --all + tx pull --all This command will leave the ``.po`` files needed for building the documentation in the target language under ``locale//LC_MESSAGES``. @@ -176,9 +176,9 @@ Build the documentation in target language Finally, to build our documentation in Spanish(Argentina) we need to tell Sphinx builder the target language with the following command: -.. code-block:: console +.. prompt:: bash $ - $ 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:: @@ -197,21 +197,23 @@ Once you have done changes in your documentation, you may want to make these add #. Create the ``.pot`` files: - .. code-block:: console + .. prompt:: bash $ - $ sphinx-build -b gettext . _build/gettext + sphinx-build -b gettext . _build/gettext -.. For the manual workflow, we need to run this command + For the manual workflow, we need to run this command - $ sphinx-intl update -p _build/gettext -l es_AR -l pt_BR + .. prompt:: bash $ + + sphinx-intl update -p _build/gettext -l es_AR -l pt_BR #. Push new files to Transifex - .. code-block:: console + .. prompt:: bash $ - $ tx push --sources + tx push --sources Build documentation from up to date translation @@ -221,16 +223,16 @@ When translators have finished their job, you may want to update the documentati #. Pull up to date translations from Transifex: - .. code-block:: console + .. prompt:: bash $ - $ tx pull --all + tx pull --all #. Commit and push these changes to our repo - .. code-block:: console + .. prompt:: bash $ - $ 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. diff --git a/docs/intro/getting-started-with-mkdocs.rst b/docs/intro/getting-started-with-mkdocs.rst index 04b09f945f7..5f6139db7a8 100644 --- a/docs/intro/getting-started-with-mkdocs.rst +++ b/docs/intro/getting-started-with-mkdocs.rst @@ -20,15 +20,15 @@ Quick start Assuming you have Python already, `install MkDocs`_: -.. sourcecode:: bash +.. prompt:: bash $ - $ pip install mkdocs + pip install mkdocs Setup your MkDocs project: -.. sourcecode:: bash +.. prompt:: bash $ - $ mkdocs new . + mkdocs new . This command creates ``mkdocs.yml`` which holds your MkDocs configuration, and ``docs/index.md`` which is the Markdown file @@ -37,9 +37,9 @@ that is the entry point for your documentation. You can edit this ``index.md`` file to add more details about your project and then you can build your documentation: -.. sourcecode:: bash +.. prompt:: bash $ - $ mkdocs serve + mkdocs serve This command builds your Markdown files into HTML and starts a development server to browse your documentation. diff --git a/docs/yaml-config.rst b/docs/yaml-config.rst index 616ace4cc7d..9aac9521baf 100644 --- a/docs/yaml-config.rst +++ b/docs/yaml-config.rst @@ -278,9 +278,9 @@ installed in addition to the default ``requests`` and ``simplejson``, use the Behind the scene the following Pip command will be run: -.. code-block:: shell +.. prompt:: bash $ - $ pip install .[tests,docs] + pip install .[tests,docs] .. _issue: https://github.com/rtfd/readthedocs.org/issues From c0d752b3932ccb8cbb63f05db2acfdab034563a9 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Wed, 12 Dec 2018 15:26:20 +0530 Subject: [PATCH 05/13] complete the update of docs --- docs/api/v2.rst | 8 +- docs/contribute.rst | 22 +++-- docs/custom_installs/elasticsearch.rst | 72 +++++++++++------ docs/custom_installs/local_rtd_vm.rst | 108 +++++++++++++++---------- docs/i18n.rst | 14 ++-- 5 files changed, 140 insertions(+), 84 deletions(-) diff --git a/docs/api/v2.rst b/docs/api/v2.rst index eed418ff6fa..d11e2c28472 100644 --- 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/contribute.rst b/docs/contribute.rst index 65d9d50424a..61f0a5cab1f 100644 --- 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 - $ pre-commit run +.. prompt:: bash $ -or to run against a specific file:: + pip install -U pre-commit + git add + pre-commit run - $ pre-commit run --files +or to run against a specific file: + +.. prompt:: bash $ + + pre-commit run --files `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 index 3612374594a..0abe74ee41e 100644 --- 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 `_. or opensource distribution like `OpenJDK `_. -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 `_. -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 index 42f14a2d220..82f0733d384 100644 --- 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//.ssh/id_rsa + vim /home//.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. diff --git a/docs/i18n.rst b/docs/i18n.rst index 19ec3896ddc..c8bd827af6d 100644 --- a/docs/i18n.rst +++ b/docs/i18n.rst @@ -269,9 +269,11 @@ Compiling to MO Gettext doesn't parse any text files, it reads a binary format for faster 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:: +available localizations, just run: - $ python manage.py compilemessages -a +.. prompt:: bash $ + + python manage.py compilemessages -a You will need to do this every time you want to push updated translations to the live site. @@ -304,12 +306,12 @@ help pages `_. #. Update files and push sources (English) to Transifex: - .. code-block:: console + .. prompt:: bash $ - $ fab i18n_push_source + fab i18n_push_source #. Pull changes (new translations) from Transifex: - .. code-block:: console + .. prompt:: bash $ - $ fab i18n_pull + fab i18n_pull From 4fd484b7c374ec07d8b84576fb13de0152c73bab Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Wed, 12 Dec 2018 15:55:37 +0530 Subject: [PATCH 06/13] correct getting started page --- docs/intro/getting-started-with-sphinx.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/intro/getting-started-with-sphinx.rst b/docs/intro/getting-started-with-sphinx.rst index 030d9e4d007..f2351752d5d 100644 --- a/docs/intro/getting-started-with-sphinx.rst +++ b/docs/intro/getting-started-with-sphinx.rst @@ -35,21 +35,21 @@ Assuming you have Python already, `install Sphinx`_: .. prompt:: bash $ - $ pip install sphinx + pip install sphinx Create a directory inside your project to hold your docs: .. prompt:: bash $ - $ cd /path/to/project - $ mkdir docs + cd /path/to/project + mkdir docs Run ``sphinx-quickstart`` in there: .. prompt:: bash $ - $ 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 @@ -61,7 +61,7 @@ or `this template`_ if you need help). Build them to see how they look: .. prompt:: bash $ - $ make html + make html Your ``index.rst`` has been built into ``index.html`` in your documentation output directory (typically ``_build/html/index.html``). @@ -90,7 +90,7 @@ We support this natively on Read the Docs, and you can do it locally: .. prompt:: bash $ - $ pip install recommonmark + pip install recommonmark Then in your ``conf.py``: From 882af24b654cea52a4bc0a708dc6392cd6371adc Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Wed, 12 Dec 2018 21:37:27 +0530 Subject: [PATCH 07/13] update .rstconfig --- docs/.rstcheck.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index 1b093d3f696..0ebdd74410e 100644 --- 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) From 7ae7b576c52cd24faa980e2ff963c4f672c2a53c Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Wed, 12 Dec 2018 22:10:53 +0530 Subject: [PATCH 08/13] fix lint --- docs/custom_installs/local_rtd_vm.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/custom_installs/local_rtd_vm.rst b/docs/custom_installs/local_rtd_vm.rst index 82f0733d384..8d0a5c379b2 100644 --- a/docs/custom_installs/local_rtd_vm.rst +++ b/docs/custom_installs/local_rtd_vm.rst @@ -79,10 +79,10 @@ Configure the RTD Server and Superuser 1. Run the following commands. -.. prompt:: bash $ + .. prompt:: bash $ - ./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: :: @@ -127,10 +127,10 @@ Possible Error and Resolution 1. In your machine, navigate to the ``.ssh`` folder. -.. prompt:: bash $ + .. prompt:: bash $ - cd .ssh/ - cat id_rsa + cd .ssh/ + cat id_rsa 2. Copy the entire Private Key. 3. Now, SSH to the VM. From efe21a6db4ac2e31f73d97cc096abe273794483f Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Thu, 27 Dec 2018 20:31:41 +0530 Subject: [PATCH 09/13] add improvements --- docs/custom_installs/local_rtd_vm.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/custom_installs/local_rtd_vm.rst b/docs/custom_installs/local_rtd_vm.rst index 8d0a5c379b2..101f5bb974b 100644 --- a/docs/custom_installs/local_rtd_vm.rst +++ b/docs/custom_installs/local_rtd_vm.rst @@ -5,7 +5,7 @@ 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: .. prompt:: bash $ @@ -15,7 +15,7 @@ Assumptions and Prerequisites sudo apt-get install libevent-dev sudo easy_install pip -* Git +* Git: .. prompt:: bash $ @@ -23,7 +23,7 @@ Assumptions and Prerequisites * Git repo is ``git.corp.company.com:git/docs/documentation.git`` * Source documents are in ``../docs/source`` -* Sphinx +* Sphinx: .. prompt:: bash $ @@ -37,7 +37,7 @@ 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 $ @@ -52,7 +52,7 @@ 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 $ @@ -60,7 +60,7 @@ Possible Error and Resolution 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 +On Debian 8 (jessie) the command is slightly different: .. prompt:: bash $ @@ -77,7 +77,7 @@ Also don't forget to re-run the dependency installation Configure the RTD Server and Superuser ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. Run the following commands. +1. Run the following commands: .. prompt:: bash $ @@ -93,7 +93,7 @@ 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 $ @@ -108,7 +108,7 @@ 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 $ @@ -125,7 +125,7 @@ Possible Error and Resolution **Workaround-1** -1. In your machine, navigate to the ``.ssh`` folder. +1. In your machine, navigate to the ``.ssh`` folder: .. prompt:: bash $ @@ -134,7 +134,7 @@ Possible Error and Resolution 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 $ @@ -144,7 +144,7 @@ Possible Error and Resolution **Workaround 2** -SSH to the VM using the ``-A`` directive. +SSH to the VM using the ``-A`` directive: .. prompt:: bash $ From 9509b9b7ba8ee0aaa60ecb143cb4c18ab0cdfaac Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Fri, 28 Dec 2018 16:36:48 +0530 Subject: [PATCH 10/13] adjust spaces for comment --- docs/guides/manage-translations.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/guides/manage-translations.rst b/docs/guides/manage-translations.rst index 8b79873c007..bf569664a43 100644 --- a/docs/guides/manage-translations.rst +++ b/docs/guides/manage-translations.rst @@ -202,11 +202,9 @@ Once you have done changes in your documentation, you may want to make these add sphinx-build -b gettext . _build/gettext - For the manual workflow, we need to run this command + .. For the manual workflow, we need to run this command - .. prompt:: bash $ - - 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 From 8789e1b19368c11b70125b887c5fe28e6144cba6 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Fri, 28 Dec 2018 16:41:36 +0530 Subject: [PATCH 11/13] again adjust spaces for comments --- docs/guides/manage-translations.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/manage-translations.rst b/docs/guides/manage-translations.rst index bf569664a43..d4d2db8767f 100644 --- a/docs/guides/manage-translations.rst +++ b/docs/guides/manage-translations.rst @@ -202,9 +202,9 @@ Once you have done changes in your documentation, you may want to make these add sphinx-build -b gettext . _build/gettext - .. For the manual workflow, we need to run this command + .. 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 From bc0d9bf4e1ff7f94502c03371ffe96f4bac14822 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Thu, 10 Jan 2019 15:49:56 +0530 Subject: [PATCH 12/13] add css file --- docs/_static/css/sphinx_prompt_css.css | 13 +++++++++++++ docs/conf.py | 4 ++++ 2 files changed, 17 insertions(+) create mode 100644 docs/_static/css/sphinx_prompt_css.css diff --git a/docs/_static/css/sphinx_prompt_css.css b/docs/_static/css/sphinx_prompt_css.css new file mode 100644 index 00000000000..33c3eb3e567 --- /dev/null +++ b/docs/_static/css/sphinx_prompt_css.css @@ -0,0 +1,13 @@ +/* CSS for sphinx-prompt */ + +.highlight { + border: 1px solid #e1e4e5; + overflow-x: auto; + margin: 1px 0 24px 0; + padding: 12px 12px; +} + +.prompt1 { + font-size: 12px; + line-height: 1.4; +} diff --git a/docs/conf.py b/docs/conf.py index 9248bb8f5b0..958c0c77aa5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -83,3 +83,7 @@ # Activate autosectionlabel plugin autosectionlabel_prefix_document = True + + +def setup(app): + app.add_stylesheet('css/sphinx_prompt_css.css') From e06869e12338783d8ce09a4e6a9534a57cc09986 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Thu, 10 Jan 2019 16:09:56 +0530 Subject: [PATCH 13/13] make css classes more specific --- docs/_static/css/sphinx_prompt_css.css | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_static/css/sphinx_prompt_css.css b/docs/_static/css/sphinx_prompt_css.css index 33c3eb3e567..d1d06f8e67c 100644 --- a/docs/_static/css/sphinx_prompt_css.css +++ b/docs/_static/css/sphinx_prompt_css.css @@ -1,13 +1,13 @@ /* CSS for sphinx-prompt */ -.highlight { +pre.highlight { border: 1px solid #e1e4e5; overflow-x: auto; margin: 1px 0 24px 0; padding: 12px 12px; } -.prompt1 { +pre.highlight span.prompt1 { font-size: 12px; line-height: 1.4; }