Merge pull request #5139 from YosysHQ/docs-preview-bugpoint

Docs: Add bugpoint guide

Author: KrystalDelusion

CONTRIBUTING.md

@@ -19,14 +19,14 @@ much easier for someone to respond and help.
 
 ### Bug reports
 
-Before you submit an issue, please have a search of the existing issues in case
-one already exists.  Making sure that you have a minimal, complete and
-verifiable example (MVCE) is a great way to quickly check an existing issue
-against a new one.  Stack overflow has a guide on [how to create an
-MVCE](https://stackoverflow.com/help/minimal-reproducible-example).  The
-[`bugpoint`
-command](https://yosyshq.readthedocs.io/projects/yosys/en/latest/cmd/bugpoint.html)
-in Yosys can be helpful for this process.
+Before you submit an issue, please check out the [how-to guide for
+`bugpoint`](https://yosys.readthedocs.io/en/latest/using_yosys/bugpoint.html).
+This guide will take you through the process of using the [`bugpoint`
+command](https://yosys.readthedocs.io/en/latest/cmd/bugpoint.html) in Yosys to
+produce a [minimal, complete and verifiable
+example](https://stackoverflow.com/help/minimal-reproducible-example) (MVCE).
+Providing an MVCE with your bug report drastically increases the likelihood that
+someone will be able to help resolve your issue.
 
 
 # Using pull requests

docs/source/cmd_ref.rst

@@ -1,5 +1,3 @@
-.. _cmd_ref:
-
 ================================================================================
 Command line reference
 ================================================================================

docs/source/conf.py

@@ -64,7 +64,6 @@
 
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True
-autosectionlabel_maxdepth = 1
 
 # include todos for previews
 extensions.append('sphinx.ext.todo')

docs/source/getting_started/scripting_intro.rst

@@ -26,7 +26,7 @@ of the comment is a semicolon ``;`` or a new line.
 .. code-block::
    :caption: Using the ``-p`` option
 
-   $ yosys -p "read_verilog fifo.v; :this is a comment; prep"
+   $ yosys -p 'read_verilog fifo.v; :this is a comment; prep'
 
 .. warning::
 
@@ -42,6 +42,13 @@ will be raised by Yosys.  `exec` provides a much more flexible way of executing
 commands, allowing the output to be logged and more control over when to
 generate errors.
 
+.. warning::
+
+   Take care when using the ``yosys -p`` option.  Some shells such as bash will
+   perform substitution options inside of a double quoted string, such as ``!``
+   for history substitution and ``$`` for variable substitution; single quotes
+   should be used instead to pass the string to Yosys without substitution.
+
 The synthesis starter script
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~