How to Add an Example Flowgraph to a Block Doc: Difference between revisions

From GNU Radio
Jump to navigation Jump to search
(reorganize)
Line 1: Line 1:
<!-- How_to_Add_an_Example_Flowgraph_to_a_Block_Doc.mediawiki -->
== Why? ==
== Why? ==
<p>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!</p>
<p>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 did not have an Example Flowgraph!</p>


== To which pages? ==
== To which pages? ==
Line 8: Line 9:


== How? ==
== How? ==
The following steps use [[Complex To Float]] as a specific example.


=== Sign into the Wiki ===
=== Sign into the Wiki ===


<p>If you have a Wiki account, sign in before proceeding. Otherwise you won't be able to upload the example screenshot.<br>
<p>If you have a Wiki account, sign in before proceeding. Otherwise you won't be able to upload the files.<br>
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.</p>
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.</p>


=== Overview ===
=== Find or Create a Flowgraph ===
The following steps use [[Complex To Float]] as a specific example.


# Find or create a flowgraph containing the subject block (see below).
# Find or create a flowgraph containing the subject block.
# Load and execute the flowgraph to test that it works!
# Load and execute the flowgraph to test that it works!
# Make a screen capture (see below)
# Go to [[Special:Upload]], Choose File, and upload it.
# Copy the file name. Note whether the displayed pixel dimensions list a width < 800 px.
# Open the subject block doc and select the 'Edit' tab next to the 'Read' tab.
# Below the <code>== Example Flowgraph ==</code> line, if there is any placeholder text, delete it and enter the flowgraph file information in the following format:<p><code><nowiki>[[File:SSB_rcv_weaver_fg.png|800px]]</nowiki></code> <br> where <code>File:SSB_rcv_weaver_fg.png</code> is your screenshot, and the <code>800px</code> is the width to display. <br>Note: if the original pixel width dimension is less than 800, omit <code>|800px</code>.</p>
# Find the line which contains <code><nowiki>[[Category:Pages with no Example Flowgraph]]</nowiki></code> and remove it.
# In the Summary entry box, enter "add Example Flowgraph"
# Click "Show preview" to examine what you have done.
# In addition to checking the Example Flowgraph, scroll to the bottem of the page and check that the only Category shown is "Block Docs".
# 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 <code>gnuradio-config-info --prefix</code> outputs, under <code>${prefix}/share/gnuradio/examples</code>.
If you prefer working on the source code, you can check the <code>grc/</code> directory in the module that the block comes from – in the case of [[Complex_to_Float|Complex to Float]] that would be <code>gnuradio/gr-blocks/grc</code>; you can find that on the [https://github.com/gnuradio/gnuradio/tree/main/gr-blocks/grc 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 <code>name of your flowgraph_fg.png</code> (e.g. <code>SSB_rcv_weaver_fg.png</code>).
== Creating a new Example Flowgraph ==
TODO: When to do this?


=== What makes a good Example Flowgraph? ===
=== Screen Capture the Flowgraph Image ===


* TODO: Full sentences
<ol>
* TODO: Illustrations
<li>In GRC, select File -> Screen Capture</li>
<li>Change the file type in the lower right corner to PNG</li>
<li>Change the filename to "<your flowgraph file>_fg.png" (e.g. <code>SSB_rcv_weaver_fg.png</code>)</li>
<li>Change the folder to '~/Pictures/Screenshots'</li>
<li>Save</li>
</ol>


----
=== Upload the Screen Capture ===


* Illustrates for what the block is usually used for
<ol>
** '''Not''' just "Null Source -> Block -> Null Sink", that doesn't help
<li>Go to [[Special:Upload]], Choose File, select the Screen Capture file, and upload it.
* Is limited in scope
<li>Save the file name and pixel dimensions in your notes.<br>
** If you want to illustrate [[Multiply_Const|Multiplication with a Constant]], don't do it by showing a 50-Block flowgraph that implements a complicated transceiver system
    e.g. <code>File:SSB_rcv_weaver_fg.png  1,552 × 623 pixels</code></li>
* If the block has parameters, shows how the relate to the context of the Flowgraph
</ol>
* 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 the Flowgraph .grc File ===


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.  
<ol>
<li>Go to [[Special:Upload]], Choose File, select the flowgraph .grc file, and upload it.
<li>Save the file name in your notes.<br>
    e.g. <code>File:SSB_rcv_weaver.grc</code></li>
</ol>


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!
=== Edit the Block Doc page ===


So, if you're versed enough in <code>git</code> 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!
<ol>
<li>Open the subject block doc and select the 'Edit' tab next to the 'Read' tab.</li>
<li>Below the <code>== Example Flowgraph ==</code> line, if there is any placeholder text, delete it and enter the flowgraph file information in the following format:
        <code><nowiki>[[File:SSB_rcv_weaver_fg.png|800px]]</nowiki></code><br>
        where <code>File:SSB_rcv_weaver_fg.png</code> is your screenshot, and the <code>800px</code> is the width to display. <br>Note: if the original pixel width is less than 800, omit <code>|800px</code>.</li>
<li>Find the line which contains <code><nowiki>[[Category:Pages with no Example Flowgraph]]</nowiki></code> and delete it.</li>
<li>In the Summary entry box, enter "add Example Flowgraph"</li>
<li>Click "Show preview" to examine what you have done.</li>
<li>In addition to checking the Example Flowgraph, scroll to the bottem of the page and check that the only Category shown is "Block Docs".</li>
<li>Make any corrections needed and then click "Save page".</li>
</ol>


== Getting Help ==
== Getting Help ==


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

Revision as of 00:51, 8 April 2025

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 did 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?

The following steps use Complex To Float as a specific example.

Sign into the Wiki

If you have a Wiki account, sign in before proceeding. Otherwise you won't be able to upload the files.
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.

Find or Create a Flowgraph

  1. Find or create a flowgraph containing the subject block.
  2. Load and execute the flowgraph to test that it works!

Screen Capture the Flowgraph Image

  1. In GRC, select File -> Screen Capture
  2. Change the file type in the lower right corner to PNG
  3. Change the filename to "<your flowgraph file>_fg.png" (e.g. SSB_rcv_weaver_fg.png)
  4. Change the folder to '~/Pictures/Screenshots'
  5. Save

Upload the Screen Capture

  1. Go to Special:Upload, Choose File, select the Screen Capture file, and upload it.
  2. Save the file name and pixel dimensions in your notes.
    e.g. File:SSB_rcv_weaver_fg.png 1,552 × 623 pixels

Upload the Flowgraph .grc File

  1. Go to Special:Upload, Choose File, select the flowgraph .grc file, and upload it.
  2. Save the file name in your notes.
    e.g. File:SSB_rcv_weaver.grc

Edit the Block Doc page

  1. Open the subject block doc and select the 'Edit' tab next to the 'Read' tab.
  2. 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 is less than 800, omit |800px.
  3. Find the line which contains [[Category:Pages with no Example Flowgraph]] and delete it.
  4. In the Summary entry box, enter "add Example Flowgraph"
  5. Click "Show preview" to examine what you have done.
  6. In addition to checking the Example Flowgraph, scroll to the bottem of the page and check that the only Category shown is "Block Docs".
  7. Make any corrections needed and then click "Save page".

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 the #Docs:gnuradio.org room.

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