How to Add an Example Flowgraph to a Block Doc

From GNU Radio
Jump to navigation Jump to search

Why?

Part of the value of our Block Doc pages is having an Example Flowgraph to show how that block can be used. In a recent review of our 555 current blocks, 214 of them do not have an Example Flowgraph!

To which pages?

Look at Pages with no Example Flowgraph and Documentation Stubs for the lists of pages in need of Example Flowgraphs.

This document describes the process to add an Example Flowgraph to an existing Block Doc; you'll find all of them in the Category Block Docs.

How?

Sign into the Wiki

If you have a Wiki account, sign in before proceeding. Otherwise you won't be able to upload the example screenshot.
If you don't have an account, click on "Request account" at the top right of any of our wiki pages (including this one). Then fill in the fields. It may take a day or two for a moderator to approve you.

Overview

The following steps use Complex_To_Float as a specific example.

  1. Find or create a flowgraph containing the subject block.
  2. Load and execute the flowgraph to test that it works!
  3. Make a screen capture (see below)
  4. Go to Special:Upload, Choose File, and open it.
  5. Save the file name and pixel dimensions in your notes.
    e.g. File:SSB_rcv_weaver_fg.png 1,552 × 623 pixels
  6. Open the subject block doc and select the 'Edit' tab next to the 'Read' tab.
  7. Below the == Example Flowgraph == line, if there is any placeholder text, delete it and enter the flowgraph file information in the following format: [[File:SSB_rcv_weaver_fg.png|800px]]
    where File:SSB_rcv_weaver_fg.png is your screenshot, and the 800px is the width to display.
    Note: if the original pixel width dimension is less than 800, use that value instead of the 800 in the example.
  8. Find the line which contains [[Category:Pages with no Example Flowgraph]] and delete it.
  9. In the Summary entry box, enter "add Example Flowgraph"
  10. Click "Show preview" to examine what you have done.
  11. In addition to checking the Example Flowgraph, scroll to the bottem of the page and check that the only Category shown is "Block Docs".
  12. Make any corrections needed and then click "Save page".

Individual Steps

Finding an existing flowgraph

If you're using the Qt version of GRC, you fill find the Examples… menu point in the File menu. This is not available in the default (Gtk) GRC.

You can check the installed examples that came with GNU Radio for an existing flow graph. You'll find them in the installation prefix, i.e., in the directory that running gnuradio-config-info --prefix outputs, under ${prefix}/share/gnuradio/examples.

If you prefer working on the source code, you can check the grc/ directory in the module that the block comes from – in the case of Complex to Float that would be gnuradio/gr-blocks/grc; you can find that on the GNU Radio source code repository.

Capturing an image of the Flowgraph

TODO: Explain in morer & gooder words


  • In the View Menu, activate Show parameter expressions in block (TODO: That's GTK-GRC, check how it is in Qt-GRC)
  • Make sure the flow graph is still tidy (see below on creating one)
  • File menu: Screen capture.
  • Make sure "PNG Files" is selected as file type.
  • Save flowgraph in a directory you'll find it again; name it name of your flowgraph_fg.png (e.g. SSB_rcv_weaver_fg.png).

Barry's original wording:


  • In GRC, select File -> Screen Capture
  • Change the filename to "<your file>_fg.png" (e.g. SSB_rcv_weaver_fg.png)
  • Change the folder to '~/Pictures/Screenshots'

Creating a new Example Flowgraph

TODO: When to do this?

What makes a good Example Flowgraph?

  • TODO: Full sentences
  • TODO: Illustrations
  • Illustrates for what the block is usually used for
    • Not just "Null Source -> Block -> Null Sink", that doesn't help
  • Is limited in scope
    • If you want to illustrate Multiplication with a Constant, don't do it by showing a 50-Block flowgraph that implements a complicated transceiver system
  • If the block has parameters, shows how the relate to the context of the Flowgraph
  • Is tidy
    • No upside-down blocks,
    • no disabled blocks,
    • connections as straight as feasible,
    • no overlapping blocks, and
    • no "ratsnests" of confusing connections (maybe use Virtual Sink / Virtual Source?)
  • Uses the "Comment" field (in the "Advanced" tab in the Block properties) on all blocks that are not self-explanatory

After the creation of the Example Flowgraph

Upload a screen capture as described above, add the image to the block documentation page, and remove the "Pages with no Example Flowgraph" category link from that page.

If the flowgraph is a good example, chances are good we'd want to have it as part of GNU Radio, so it gets installed to new user's computer in the future!

So, if you're versed enough in git and github usage, please add the flowgraph to the appropriate gr-{module}/examples directory and open a pull request. If you'd prefer someone else to handle this, let the Documentation team know!

Getting Help

You can always ask questions on our Matrix server in the #gnuradio:gnuradio.org room; if it's specifically about help with editing documentation, please reach out to the documentation team in #Docs:gnuradio.org room.

Retrieved from "https://wiki.gnuradio.org/index.php?title=How_to_Add_an_Example_Flowgraph_to_a_Block_Doc&oldid=14889"