get_started¶

Title: Getting Started¶

The name of this page is get_started and its title is Title: Getting Started . All of the headings below begin with Heading: .

Heading: Steps¶

Use pip as follows to install the most recent stable version of xrst:
```
pip install xrst
```
If you like, you can replace this by the most recent test version of xrst using the following commands:
```
pip uninstall -y xrst
pip install --index-url https://test.pypi.org/simple/ xrst
```
Create an empty directory and make it your current working directory.
Create an empty file called xrst.toml (the xrst configure file) in the working directory. The empty file tells xrst to use all its default configuration settings.
Create a file called project.xrst, in the working directory, with the contents of this example file . Note that project.xrst is the default location for the xrst root file. You could change the location of the root file to get_started.xrst by entering the following in your xrst.toml file:
```
[root_file]
default = 'get_started.xrst'
```
Execute the following command:
```
xrst
```
Use your web browser to open the file below (this file name is relative to your working directory):
```
build/html/get_started.html
```
You may have gotten spelling warnings for two reasons:
1. The project dictionary for this example is empty while the one used to test xrst is not.
2. You are using is different version of the spell checker from the one used to test xrst.
You can fix these warning by adding or removing words in the spell command at the beginning of the get_started.xrst file. If you do this correctly and re-execute the xrst command, the spelling warnings should not appear.
You should have gotten a warning that none of the input_files commands succeeded. These commands are used to check if all the input files get used. You can remove this check by adding the text below at the end of your xrst.toml file:
```
[input_files]
data = [ ]
```
If you then re-execute the xrst command, the input files warning should not appear.

Heading: This Example File¶

The file below demonstrates the use of xrst_begin, xrst_end, xrst_spell, xrst_literal and heading references :

# SPDX-License-Identifier: GPL-3.0-or-later
# SPDX-FileCopyrightText: Bradley M. Bell <bradbell@seanet.com>
# SPDX-FileContributor: 2020-25 Bradley M. Bell
# ----------------------------------------------------------------------------
{xrst_begin get_started}
{xrst_spell
   url
}

Title: Getting Started
######################
The name of this page is ``get_started`` and its title is
``Title: Getting Started`` .
All of the headings below begin with ``Heading:`` .

Heading: Steps
**************

#. Use pip as follows to install the most recent stable version of xrst::

      pip install xrst

#. If you like, you can replace this by the most recent test version
   of xrst using the following commands::

      pip uninstall -y xrst
      pip install --index-url https://test.pypi.org/simple/ xrst

#. Create an empty directory and make it your current working directory.

#. Create an empty file called ``xrst.toml`` (the xrst configure file)
   in the working directory. The empty file tells xrst to use
   all its default configuration settings.

#. Create a file called ``project.xrst``, in the working directory,
   with the contents of
   :ref:`this example file<get_started@Heading: This Example File>` .
   Note that ``project.xrst`` is the default location for the xrst root file.
   You could change the location of the root file to  ``get_started.xrst``
   by entering the following in your ``xrst.toml`` file::

      [root_file]
      default = 'get_started.xrst'

#. Execute the following command::

      xrst

#. Use your web browser to open the file below
   (this file name is relative to your working directory)::

      build/html/get_started.html

#. You may have gotten spelling warnings for two reasons:

   #. The project dictionary for this example is empty while the one used
      to test xrst is not.
   #. You are using is different version of the spell checker
      from the one used to test xrst.

   You can fix these warning by adding or removing words in the
   spell command at the beginning of the get_started.xrst file.
   If you do this correctly and re-execute the xrst command,
   the spelling warnings should not appear.

#. You should have gotten a warning that none of the input_files commands
   succeeded. These commands are used to check if all the input files get used.
   You can remove this check by adding the text below at the end of your
   xrst.toml file::

      [input_files]
      data = [ ]

   If you then re-execute the xrst command, the input files
   warning should not appear.


Heading: Links to this Page
***************************

- :ref:`get_started-name`

- :ref:`get_started-title`

- :ref:`get_started@Heading: Steps`

- :ref:`get_started@Heading: Links to this Page`

- :ref:`get_started@Heading: This Example File`

Heading: This Example File
**************************
The file below demonstrates the use of
``xrst_begin``,  ``xrst_end``, ``xrst_spell``, ``xrst_literal``
and heading references :
{xrst_literal}

{xrst_end get_started}