docs: Update the XBlock Tutorial Getting Started section

openedx · Dec 19, 2023 · 83b2ee8 · 83b2ee8
1 parent 6367f8a
commit 83b2ee8
Show file tree

Hide file tree

Showing 10 changed files with 50 additions and 49 deletions.
diff --git a/docs/links.rst b/docs/links.rst
@@ -31,6 +31,8 @@
 
 .. _VirtualEnvWrapper: http://virtualenvwrapper.readthedocs.io/en/latest
 
+.. _managing different Python versions with virtualenv: https://saturncloud.io/blog/how-to-use-different-python-versions-with-virtualenv/
+
 .. _XBlock SDK: https://github.com/openedx/xblock-sdk
 
 .. _PyEnv: https://github.com/yyuu/pyenv

diff --git a/docs/xblock-tutorial/Images/sdk_ui.png b/docs/xblock-tutorial/Images/sdk_ui.png
diff --git a/docs/xblock-tutorial/getting_started/create_first_xblock.rst b/docs/xblock-tutorial/getting_started/create_first_xblock.rst
@@ -1,8 +1,8 @@
 .. _Create Your First XBlock:
 
-#########################
+########################
 Create Your First XBlock
-#########################
+########################
 
 Before you continue, make sure that you have :ref:`set up the XBlock SDK <Set
 Up the XBlock Software Development Kit>`. You then create the XBlock and deploy
@@ -20,9 +20,9 @@ it in the XBlock SDK.
 
 .. include:: ../reusable/run_server.rst
 
-******************
+**********
 Next Steps
-******************
+**********
 
 You have now completed the Getting Started section of the XBlock tutorial. In
 the next sections, you will learn :ref:`how to use the XBlock SDK <Using the

diff --git a/docs/xblock-tutorial/getting_started/prereqs.rst b/docs/xblock-tutorial/getting_started/prereqs.rst
@@ -1,8 +1,8 @@
 .. _Install XBlock Prerequisites:
 
-################################
+############################
 Install XBlock Prerequisites
-################################
+############################
 
 To build an XBlock, you must have the following tools on your computer.
 
@@ -11,31 +11,31 @@ To build an XBlock, you must have the following tools on your computer.
  :depth: 1
 
 
-***********
+**********
 Python 3.8
-***********
+**********
 
 To run the a virtual environment and the XBlock SDK, and to build an XBlock,
 you must have Python 3.8 installed on your computer.
 
 `Download Python`_ for your operating system and follow the installation
 instructions.
 
-****
+***
 Git
-****
+***
 
-EdX repositories, including XBlock and the XBlock SDK, are stored on GitHub.
+Open edX repositories, including XBlock and the XBlock SDK, are stored on GitHub.
 
 To build your own XBlock, and to deploy it later, you must use Git for source
 control.
 
 If you do not have Git installed, or you are are unfamiliar with the tool, see
 the `GitHub Help`_.
 
-************************
+*********************
 A Virtual Environment
-************************
+*********************
 
 It is recommended that you develop your XBlock using a Python virtual
 environment. A virtual environment is a tool to keep the dependencies required

diff --git a/docs/xblock-tutorial/getting_started/setup_sdk.rst b/docs/xblock-tutorial/getting_started/setup_sdk.rst
@@ -1,8 +1,8 @@
 .. _Set Up the XBlock Software Development Kit:
 
-###########################################
+##########################################
 Set Up the XBlock Software Development Kit
-###########################################
+##########################################
 
 Before you continue, make sure that you are familiar with the subjects in the
 :ref:`Install XBlock Prerequisites` section.
@@ -14,9 +14,9 @@ SDK`_ in a virtual environment. To do this, complete the following steps.
  :local:
  :depth: 1
 
-********************************************
+**********************************
 Create a Directory for XBlock Work
-********************************************
+**********************************
 
 It is recommended that you create a directory in which to store all your XBlock
 work, including a virtual environment, the XBlock SDK, and the XBlocks you
@@ -38,11 +38,14 @@ develop.
 
 .. _Create and Activate the Virtual Environment:
 
-********************************************
+*******************************************
 Create and Activate the Virtual Environment
-********************************************
+*******************************************
 
-You must have a virtual environment tool installed on your computer. For more information, see :ref:`Install XBlock Prerequisites`.
+You must have a virtual environment tool installed on your computer. For more
+information, see :ref:`Install XBlock Prerequisites`. If you have multiple
+Python versions on your machine, see `managing different Python versions with
+virtualenv`_.
 
 Then create the virtual environment in your ``xblock_development`` directory.
 
@@ -51,23 +54,26 @@ Then create the virtual environment in your ``xblock_development`` directory.
 
    .. code-block:: bash
 
-      $ virtualenv venv
+      $ virtualenv xblock-env
 
 #. Run the following command to activate the virtual environment.
 
    .. code-block:: bash
 
-      $ source venv/bin/activate
+      $ source xblock-env/bin/activate
 
    When the virtual environment is activated, the command prompt shows the name
    of the virtual directory in parentheses.
 
    .. code-block:: none
 
-      (venv) $
+      (xblock-env) $
 
 .. include:: ../reusable/clone_sdk.rst
 
-When the requirements are installed, you are in the ``xblock_development`` directory, which contains the ``venv`` and ``xblock-sdk`` subdirectories. You can now :ref:`create your first XBlock <Create Your First XBlock>`.
+When the requirements are installed, you are in the ``xblock_development``
+directory, which contains the ``var``, ``xblock-env``, and ``xblock-sdk``
+subdirectories. You can now :ref:`create your first XBlock <Create Your First
+XBlock>`.
 
 .. include:: ../../links.rst
diff --git a/docs/xblock-tutorial/reusable/clone_sdk.rst b/docs/xblock-tutorial/reusable/clone_sdk.rst
@@ -14,29 +14,29 @@ requirements. To do this, complete the following steps at a command prompt.
 
    .. code-block:: bash
 
-      (venv) $ git clone https://github.com/openedx/xblock-sdk.git
+      (xblock-env) $ git clone https://github.com/openedx/xblock-sdk.git
 
 #. In the same directory, create an empty directory called `var`.
 
    .. code-block:: bash
 
-      (venv) $ mkdir var
+      (xblock-env) $ mkdir var
 
 #. Run the following command to change to the ``xblock-sdk`` directory.
 
    .. code-block:: bash
   
-      (venv) $ cd xblock-sdk
+      (xblock-env) $ cd xblock-sdk
 
 #. Run the following commands to install the XBlock SDK requirements.
 
    .. code-block:: bash
   
-      (venv) $ make install
+      (xblock-env) $ make install
 
 #. Run the following command to return to the ``xblock_development`` directory,
    where you will perform the rest of your work.
 
    .. code-block:: bash
   
-      (venv) $ cd ..
+      (xblock-env) $ cd ..
diff --git a/docs/xblock-tutorial/reusable/create_db.rst b/docs/xblock-tutorial/reusable/create_db.rst
@@ -10,13 +10,5 @@ database.
 
    .. code-block:: none
 
-      (venv) $ python xblock-sdk/manage.py migrate
+      (xblock-env) $ python xblock-sdk/manage.py migrate
 
-#. You are prompted to indicate whether or not to create a Django superuser.
-
-   .. code-block:: none
-
-      You just installed Django's auth system, which means you don't have any
-      superusers defined. Would you like to create one now? (yes/no):
-
-#. Enter ``no``.
diff --git a/docs/xblock-tutorial/reusable/create_xblock.rst b/docs/xblock-tutorial/reusable/create_xblock.rst
@@ -1,18 +1,19 @@
-******************
+****************
 Create an XBlock
-******************
+****************
 
 You use the XBlock SDK to create skeleton files for an XBlock. To do this,
 follow these steps at a command prompt.
 
-#. Change to the ``xblock_development`` directory, which contains the ``venv`` and ``xblock-sdk`` subdirectories.
+#. Change to the ``xblock_development`` directory, which contains the
+   ``var``, ``xblock-env``, and ``xblock-sdk`` subdirectories.
 
 #. Run the following command to create the skeleton
    files for the XBlock.
 
    .. code-block:: none
 
-      (venv) $ xblock-sdk/bin/workbench-make-xblock
+      (xblock-env) $ xblock-sdk/bin/workbench-make-xblock
 
    Instructions in the command window instruct you to determine a short name
    and a class name. Follow the guidelines in the command window to determine

diff --git a/docs/xblock-tutorial/reusable/install_xblock.rst b/docs/xblock-tutorial/reusable/install_xblock.rst
@@ -8,6 +8,6 @@ In the ``xblock_development`` directory, use ``pip`` to install your XBlock.
 
    .. code-block:: none
 
-      (venv) $ pip install -e myxblock
+      (xblock-env) $ pip install -e myxblock
 
 You can then test your XBlock in the XBlock SDK.
diff --git a/docs/xblock-tutorial/reusable/run_server.rst b/docs/xblock-tutorial/reusable/run_server.rst
@@ -1,6 +1,6 @@
-**************************
+*************************
 Run the XBlock SDK Server
-**************************
+*************************
 
 To see the web interface of the XBlock SDK, you must run the SDK server.
 
@@ -9,7 +9,7 @@ server.
 
    .. code-block:: none
 
-      (venv) $ python xblock-sdk/manage.py runserver
+      (xblock-env) $ python xblock-sdk/manage.py runserver
 
 .. note:: If you do not specify a port, the XBlock SDK server uses port 8000.
   To use a different port, specify it in the ``runserver`` command.
@@ -25,15 +25,15 @@ The page shows the XBlocks installed automatically with the XBlock SDK. Note
 that the page also shows the **MyXBlock** XBlock that you created in
 :ref:`Create Your First XBlock`.
 
-====================================
+==================================
 Get Help for the XBlock SDK Server
-====================================
+==================================
 
 To get help for the XBlock SDK ``runserver`` command, run the following
 command.
 
    .. code-block:: none
 
-      (venv) $ python xblock-sdk/manage.py help
+      (xblock-env) $ python xblock-sdk/manage.py help
 
 The command window lists and describes the available commands.