Commit 36f7f076 authored by Simon Spannagel's avatar Simon Spannagel
Browse files

Merge branch 'p-document-module-io' into 'master' 

docs: add module IO information in hugo and PDF

See merge request allpix-squared/allpix-squared!1008
parents a94cf300 d453271d

doc/convert/convert_markdown.py

+28 −3
Original line number Diff line number Diff line
@@ -94,7 +94,31 @@ def hugo_front_matter_convert_pandoc(string: str) -> str: 


        converted_front_matter = '# ' + yaml_data['title'] + '\n'



        # TODO: if module append module stuff

        # convert module data, check for `module_status` in front matter

        if 'module_status' in yaml_data.keys():

            # we are in a module, prepare variables for table

            module_data = {'Status': yaml_data['module_status']}

            max_tabentry_length = len(yaml_data['module_status'])

            # fetch arrays

            for key in ['module_maintainers', 'module_inputs', 'module_outputs']:

                if key in yaml_data.keys():

                    module_data[key[7].upper() + key[8:]] = yaml_data[key]

                    for element in yaml_data[key]:

                        max_tabentry_length = max(max_tabentry_length, len(element))

            # table width formatting

            table_enclosing_row = ('{:-<12} {:-<' + str(max_tabentry_length) + '}').format('', '')

            table_format_string = ('{: <12} {: <' + str(max_tabentry_length) + '}')

            # create table

            converted_front_matter += '\n' + table_enclosing_row + '\n'

            for key, value in module_data.items():

                if isinstance(value, list):

                    # if list, put entries in separate lines with key only in first line

                    converted_front_matter += table_format_string.format(key, value[0]) + '\n'

                    for count in range(1, len(value)):

                        converted_front_matter += table_format_string.format('', value[count]) + '\n'

                else:

                    converted_front_matter += table_format_string.format(key, value) + '\n'

            converted_front_matter += table_enclosing_row



        string = converted_front_matter + string_after_yaml
@@ -197,7 +221,7 @@ def latex_convert_href_references(string: str, file_path: str) -> str: 
        ref_rel_file_path = ref[1]

        ref_full_match = ref[0] + ref[1] + ref[2]

        ref_file_path = os.path.join(os.path.dirname(file_path), ref_rel_file_path)

        ref_replace = _get_path_relative_to_markdown_tree(ref_file_path).replace('\#', '-')

        ref_replace = _get_path_relative_to_markdown_tree(ref_file_path).replace('\\#', '-')

        string = re.sub(re.escape(ref_full_match), rf'\\protect\\hyperlink{{{ref_replace}}}', string)



    return string
@@ -250,7 +274,8 @@ def pandoc2latex(string: str, file_path: str, extra_args: list[str] = None) -> s 
    tmp.close()



    pandoc_args = [

        'pandoc', '-f', 'markdown+escaped_line_breaks+shortcut_reference_links+autolink_bare_uris+raw_html-raw_tex',

        'pandoc',

        '-f', 'markdown+escaped_line_breaks+shortcut_reference_links+autolink_bare_uris+multiline_tables+raw_html-raw_tex',

        '-t', 'latex',

        '--listings', '--biblatex',

        '--lua-filter', 'pandoc-gitlab-math.lua',

doc/usermanual/10_development/03_new_module.md

+4 −4
Original line number Diff line number Diff line
@@ -135,8 +135,8 @@ The `README.md` serves as the documentation for the module and should be written 
The `README.md` should follow the structure indicated in the `README.md` file of the `DummyModule` in `src/modules/Dummy`,

and should contain at least the following sections:



- A YAML header with the name of the module (`title`), a short description of the module (`description`) the maintainer

  (`module_maintainer`) and status (`module_status`) of the module.

- A YAML header with the name of the module (`title`), a short description of the module (`description`) the status

  (`module_status`) and maintainers (`module_maintainers`) of the module.



  If the module is working and well-tested, the status of the module should be `Functional`. By default, new modules are

  given the status `Immature`. The maintainer should mention the full name of the module maintainer, with their email
@@ -145,11 +145,11 @@ and should contain at least the following sections: 
  ```yaml

  title: "ModuleName"

  description: "Some short description"

  module_maintainer: "John Doe (<john.doe@example.com>)"

  module_status: "Functional"

  module_maintainers: ["John Doe (<john.doe@example.com>)"]

  ```



  In addition, the input (`module_input`) and output (`module_output`) objects of the module should be given as well.

  In addition, the input (`module_inputs`) and output (`module_outputs`) objects of the module should be given as well.



- An H2-size section named **Description**, containing a short description of the module.

src/modules/CSADigitizer/README.md

+3 −3
Original line number Diff line number Diff line
@@ -3,10 +3,10 @@ 
# SPDX-License-Identifier: CC-BY-4.0 OR MIT

title: "CSADigitizer"

description: "Digitizer emulating a Charge Sensitive Amplifier"

module_maintainer: "Annika Vauth (<annika.vauth@desy.de>), Simon Spannagel (<simon.spannagel@desy.de>)"

module_status: "Functional"

module_input: "PixelCharge"

module_output: "PixelHit"

module_maintainers: ["Annika Vauth (<annika.vauth@desy.de>)", "Simon Spannagel (<simon.spannagel@desy.de>)"]

module_inputs: ["PixelCharge"]

module_outputs: ["PixelHit"]

---



## Description

src/modules/CapacitiveTransfer/README.md

+3 −3
Original line number Diff line number Diff line
@@ -3,10 +3,10 @@ 
# SPDX-License-Identifier: CC-BY-4.0 OR MIT

title: "CapacitiveTransfer"

description: "Transfer with cross-coupling between pixels"

module_maintainer: "Mateus Vicente (mvicente@cern.ch)"

module_status: "Functional"

module_input: "PropagatedCharge"

module_output: "PixelCharge"

module_maintainers: ["Mateus Vicente (mvicente@cern.ch)"]

module_inputs: ["PropagatedCharge"]

module_outputs: ["PixelCharge"]

---



## Description

src/modules/CorryvreckanWriter/README.md

+2 −2
Original line number Diff line number Diff line
@@ -3,9 +3,9 @@ 
# SPDX-License-Identifier: CC-BY-4.0 OR MIT

title: "CorryvreckanWriter"

description: "Writes pixel hits in the Corryvreckan format"

module_maintainer: "Simon Spannagel (<simon.spannagel@cern.ch>), Daniel Hynds (<daniel.hynds@cern.ch>)"

module_status: "Functional"

module_input: "PixelHit"

module_maintainers: ["Simon Spannagel (<simon.spannagel@cern.ch>)", "Daniel Hynds (<daniel.hynds@cern.ch>)"]

module_inputs: ["PixelHit"]

---



## Description