task(GUIDEFRAME-54): update code snippet headings in docs

docs/assembly.md

@@ -9,7 +9,8 @@ permalink: assembly
 # Assembly
 The assembly file contains the functions which act to combine the various files created during the GuideFrame pipeline. The following section will list each function contained within this file and provide some insight into its use and syntax.
 
-### `assemble_audio_video()`
+
+### assemble_audio_video()
 ```python
 def assemble_audio_video(video_file, audio_file, output_file):
     # Check that both files exist
@@ -33,7 +34,8 @@ def assemble_audio_video(video_file, audio_file, output_file):
 ```
 This function takes a `video_file`, `audio_file` and `output_file` as arguments. It checks for these files before using the `ffmpeg` python package to combine them into a single file, named by the passed argument. This file then contains the combined audio and video for a single `guide_step`.
 
-### `combine_all_videos()`
+
+### combine_all_videos()
 ```python
 def combine_all_videos(output_files, final_output):
     # Temp text file to iterate through
@@ -60,7 +62,8 @@ def combine_all_videos(output_files, final_output):
 ```
 This function takes `output_files` and `final_output` as arguments. It takes the array of passed files and writes them to a newly created text file called `file_list`. The `concat` function from `ffmpeg` is used with the `file_list` passed. This is the `input` portion of the command before the `output` portion uses the `final_output` name for outputted file name. 
 
-### `assemble()`
+
+### assemble()
 ```python
 def assemble(number_of_steps):
     # Combine individual video and audio for each step by iterating through files and passing to above functions

docs/audio.md

@@ -9,7 +9,8 @@ permalink: audio
 # Audio
 The audio file contains functions designed to provide the voiceover for each GuideFrame step. It interacts with both `gTTS` and markdown in order to create these mp3 files. The following section will list each function contained within this file and provide some insight into its use and syntax.
 
-### `export_gtts()`
+
+### export_gtts()
 ```python
 def export_gtts(text, file_name):
     tts = gTTS(text)
@@ -18,7 +19,8 @@ def export_gtts(text, file_name):
 ```
 This function uses the `gTTS` python package in order to generate audio based on the user-prescribed text. It takes the `text` argument and passes it, along with a `file_name` to the native `gTTS` functions. This then writes an audio file, with the passed name and featuring the prescribed text, to the local directory.
 
-### `sleep_based_on_vo()`
+
+### sleep_based_on_vo()
 ```python
  def sleep_based_on_vo(file_name):
     audio = MP3(file_name)
@@ -27,7 +29,7 @@ This function uses the `gTTS` python package in order to generate audio based on
 ```
 This function is designed to prevent the main script's interactions from accelerating beyond the recorded voiceover. It achieves this by taking the `file_name` of the .mp3 file created during the above function. It then parses the length of this audio file before using the `sleep` function from the `time` package to sleep based on the length found in seconds. This ensures that an interaction cannot occur until the requisite voiceover clip has completed.
 
-### `pull_vo_from_markdown()`
+### pull_vo_from_markdown()
 ```python
 def pull_vo_from_markdown(md_file, step_number):
     # Open the markdown file and read
@@ -54,7 +56,8 @@ def pull_vo_from_markdown(md_file, step_number):
 ```
 This function takes the `md_file` and `step_number` as arguments. It uses these to extract the text content of the markdown file by opening it and then using the `re` package to perform a regex parse (outlined in above code comments). This pattern ensures that the text must follow a `##` heading with text matching "Step n*". Provided a match is found, it is then returned.
 
-### `generate_voiceover()`
+
+### generate_voiceover()
 ```python
 def generate_voicover(md_file, step_number):
     # Extract voiceover text from the .md file

docs/selenium.md

@@ -10,7 +10,7 @@ permalink: /selenium/
 The selenium file contains functions designed to perform the various UI-based interactions specified in a GuideFrame step. The functions act as an SDK-lite, providing an abstraction layer to users who wish to avoid more escoteric `selenium` commands. The following section will list each function contained within this file and provide some insight into its use and syntax.
 
 
-`driver_setup()`
+### driver_setup()
 ```python
 def driver_setup(driver_location):
     # Setting up with Chrome options and the ChromeDriver service
@@ -33,15 +33,15 @@ def driver_setup(driver_location):
 This function takes the `driver_location` variable extracted by `get_env_settings()` in utils. The function then adds numerous `selenium` options in to provide the optimum setup for GuideFrame. This includes using incognito mode to avoid password saving prompts and disabling the chrome banner stating the use of automation in the session. Once the various options have been set, the function returns the `driver` which will be used as an argument in all of the below functions.
 
 
-### `open_url()`
+### open_url()
 ```python
 def open_url(driver, target):
     driver.get(target)
 ```
 This function simply takes the `driver` and a url as arguments. It then opens the passed url in the browser.
 
 
-### `set_window_size()`
+### set_window_size()
 ```python
 def set_window_size(driver):
     # Try block to account for potential driver issues
@@ -56,7 +56,7 @@ def set_window_size(driver):
 This function uses the `driver` as an argument and then uses the requisite `selenium` command to maximise the browser window, ensuring a full screen representation of the session. It includes a try block to account for potential errors due to `chromedriver` updates. Should the initial command fail, it will fall back to using a 1920x1080 pixel count.
 
 
-### `find_element()`
+### find_element()
 ```python
 def find_element(driver, id):
     try:
@@ -71,7 +71,7 @@ def find_element(driver, id):
 This function takes the `driver` and an elements `id` as arguments. It then uses `selenium` functions to wait for the element to appear. This is wrapped in a try block ensuring that if an element is not found with a matching `id`, then an exception is raised.
 
 
-### `scroll_to_element()`
+### scroll_to_element()
 ```python
 def scroll_to_element(driver, href):
     try:
@@ -88,7 +88,7 @@ def scroll_to_element(driver, href):
 This function takes the `driver` and a `href` as arguments. It once again uses `selenium` functions to wait for the presence of an element. In this case however, an xpath filter is used to find the element by its `href`. Once this has occured, the `selenium` functions to scroll to an element are invoked with the result of the xpath check passed.
 
 
-### `hover_and_click()`
+### hover_and_click()
 ```python
 def hover_and_click(driver, href):
     try:
@@ -109,7 +109,7 @@ def hover_and_click(driver, href):
 This function once again takes a `driver` and `href` as arguments. It uses the same logic as the previous function to find the element by the `href` but in this case, `selenium` is invoked to perform the `move_to_element` interaction. Once this has occured, the element is clicked.
 
 
-### `hover_over_element()`
+### hover_over_element()
 ```python
 def hover_over_element(driver, href):
     try:
@@ -126,7 +126,7 @@ def hover_over_element(driver, href):
 ```
 This function is identical to the previous one with the exception that it doesn't click the element. Useful for highlight a linked button etc without following through on the click.
 
-### `click_element()`
+### click_element()
 ```python
 def click_element(driver, css_selector):
     try:
@@ -141,7 +141,7 @@ def click_element(driver, css_selector):
 This function uses similar logic to the `find_element()` function with the exception of adding a click to the sequence and using a `css_selector` rather than an `id` to locate the element. This is useful for situations where an `id` may not be static.
 
 
-### `type_into_field()`
+### type_into_field()
 ```python
 def type_into_field(driver, element_id, text):
     try:
@@ -156,7 +156,7 @@ def type_into_field(driver, element_id, text):
 This function uses the same element-locating logic seen throughout this file with the addition of a call to the `selenium` function, `send_keys` where the `text` argument from this function is passed.
 
 
-### `open_link_in_new_tab()`
+### open_link_in_new_tab()
 ```python
 def open_link_in_new_tab(driver, href):
     try:
@@ -172,7 +172,7 @@ def open_link_in_new_tab(driver, href):
 This function takes the `driver` and a `href` as an argument. It uses the `execute_script()` function within selenium to pass script arguments. In this case a window is opened using the passed `href`. The `switch_to.window()` function from `selenium` is then called where it takes the most recently opened tab as an argument. This is found using the size of the `window_handles` array and subtracting 1 to find the most recently opened window.
 
 
-### `switch_to_tab()`
+### switch_to_tab()
 ```python
 def switch_to_tab(driver, tab_index):
     try:
@@ -187,7 +187,7 @@ def switch_to_tab(driver, tab_index):
 This function takes the `driver` and `tab_index` as arguments. The user simply needs to specify which index of the array of open tabs they wish to switch to. This is wrapped in conditional logic to ensure an invalid index isn't provided. The `window_handles()` function is then called with `tab_index` passed in order to open the correct tab.
 
 
-### `take_screenshot()`
+### take_screenshot()
 ```python
 def take_screenshot(driver, file_name="screenshot.png"):
     try:
@@ -199,7 +199,7 @@ def take_screenshot(driver, file_name="screenshot.png"):
 This function takes the `driver` and a `file_name` as arguments. It has a default of "screenshot.png". It uses `selenium` to take a screenshot and use the argument to name the file.
 
 
-### `select_dropdown_option()`
+### select_dropdown_option()
 ``` python
 def select_dropdown_option(driver, dropdown_id, visible_text):
     try:
@@ -215,7 +215,7 @@ def select_dropdown_option(driver, dropdown_id, visible_text):
 This function takes the `driver`, `dropdown_id` and `visible_text` as arguments. It uses `selenium` logic to ensure that the element is clickable before using the `select_by_visible_text()` function to click on a dropdown option with text matching the functions argument.
 
 
-### `click_button_by_span_text()`
+### click_button_by_span_text()
 ```python
 def click_button_by_span_text(driver, span_text):
     try:
@@ -232,7 +232,7 @@ def click_button_by_span_text(driver, span_text):
 This function uses similar logic to other clicking functions but in this case uses an xpath filter to locate an element by the `span_text` argument passed to the function. This is useful for buttons in particular or other elements with static span text.
 
 
-### `click_element_by_xpath()`
+### click_element_by_xpath()
 ```python
 def click_element_by_xpath(driver, xpath):
     try:
@@ -247,7 +247,7 @@ def click_element_by_xpath(driver, xpath):
 This function is similar to other outlined throughout this document except that it takes an `xpath` as an argument. This allows a user to simply use a browser's `inspect` feature to select an element, right click and then select `copy xpath`. This can then be passed to this function.
 
 
-### `hover_over_element_by_xpath()`
+### hover_over_element_by_xpath()
 ```python
 def hover_over_element_by_xpath(driver, xpath):
     try:
@@ -263,7 +263,7 @@ def hover_over_element_by_xpath(driver, xpath):
 This function, similar to the above example, is similar to the other hovering functions with the exception of using `xpath` to locate elements. As above, this streamlines the user experience in terms of locating elements in the browser prior to GuideFrame script creation.
 
 
-### `highlight_github_code()`
+### highlight_github_code()
 ```python
 def highlight_github_code(driver, target):
     driver.get(target)
@@ -272,7 +272,7 @@ def highlight_github_code(driver, target):
 This function matchess the `open_url()` function but refreshes the page once it's opened. This occurs to allow the user to pass GitHub urls with line numbers for code walkthroughs. By default, when on a GitHub page, adding the line numbers to the url will not move to the requisite line. A refresh is required, hence this implementation.
 
 
-### `sleep_for()`
+### sleep_for()
 ```python
 def sleep_for(seconds):
     sleep(seconds)

docs/utils.md

@@ -10,7 +10,7 @@ permalink: /utils/
 The utils file contains functions designed to provide vital variables to other aspects of the GuideFrame logic in addition to outlining the logic of the key `guide_step`. The following section will list each function contained within this file and provide some insight into its use and syntax.
 
 
-### `get_env_settings()`
+### get_env_settings()
 ```python
 def get_env_settings():
     if len(sys.argv) > 1:
@@ -39,7 +39,7 @@ def get_env_settings():
 This function takes the system argument provided to the GuideFrame script and sets vital environmental variables based on this. This function is key in accounting for the variance in file paths, display type etc.
 
 
-### `extract_md_filename()`
+### extract_md_filename()
 ```python
 def extract_md_filename():
     script_name = sys.argv[0]
@@ -48,7 +48,7 @@ def extract_md_filename():
 This function extracts the GuideFrame scripts name from the system argument before replacing the `.py` extension with `.md`. This is performed in order to ascertain the title of the GuideFrame scripts matching markdown file. The markdown file MUST match the GuideFrame scripts title or the core logic will fail.
 
 
-### `extract_script_name()`
+### extract_script_name()
 ```python
 def extract_script_name():
     script_name = sys.argv[0]
@@ -57,7 +57,7 @@ def extract_script_name():
 This function serves a similar purpose and shares logic with `extract_md_filename()`. It is used to drop the `.py` extension in order to grab the scripts name for final output file naming.
 
 
-### ```guide_step()```
+### guide_step()
 ```python
 def guide_step(step_number, *actions, order="action-after-vo"):
     # Get the environment settings

docs/video.md

@@ -10,7 +10,7 @@ permalink: /video/
 The video file contains functions designed to provide start and stop the `ffmpeg` recordings used to capture each GuideFrame step. The following section will list each function contained within this file and provide some insight into its use and syntax.
 
 
-### `start_ffmpeg_recording()`
+### start_ffmpeg_recording()
 ```python
 def start_ffmpeg_recording(output_file, input_format, input_display):
     print("Beginning recording of clip")
@@ -36,7 +36,7 @@ It takes the `output_file`, `input_format` and `input_display` variables in orde
 It then uses `subprocess` to run the `ffmpeg` command, passing the array of flags outlined above.
 
 
-### `stop_ffmpeg_recording()`
+### stop_ffmpeg_recording()
 ```python
 def stop_ffmpeg_recording(process):
     process.stdin.write(b"q\n")  # Send 'q' to gracefully stop the recording