Fix releaseherald documentation (#1180)

* fixed releaseherald documentation

doc/newsfragments/3055_changed.fix_releaseherald_docs.rst

@@ -0,0 +1 @@
+Fix releaseherald documentation

releaseherald/docs/configuration.md

@@ -3,8 +3,7 @@
 `releaseherald` needs at least a known git repository to run. It can be provided as a command line
 parameter `--git-dir path/to/git/dir`
 or just simply running `releaseherlad` somewhere in a git repository. The root of the git repository is considered as
-the place of the config files. If no config files exists it will run with defaults, which will be detailed in the
-[Configurable Options](#configurable-options) section.
+the place of the config files. If no config files exists it will run with defaults, which will be detailed below.
 
 ## Config files
 

releaseherald/docs/plugins/stock.md

@@ -13,7 +13,7 @@ on the list). Other plugins can depend on this default behaviour and extend,alte
 This plugin responsible to render the news into an output based on a jinja2 template. This added automatically to 
 the list of plugins even if not mentioned in the config, though if a plugin implement their own rendering this can 
 be removed adding `-base_output` to the list of plugins.  
-[/configuration/](../configuration.md#base-output-plugin-configuration)
+[/configuration/](../configuration.md#base_output-plugin-configuration)
 
 ## latest
 This is a simple plugin, it adds the `--latest` commandline switch for generate and understand the 

releaseherald/releaseherald/configuration.py

@@ -19,7 +19,7 @@
 class Configuration(BaseModel):
     """
     This class represent the configuration read from the config file.
-    See attribute details in [Configuration](/configuration)
+    See attribute details in [Configuration](../configuration.md)
     """
 
     config_path: Path
@@ -62,27 +62,30 @@ def parse_sub_config(
         """
         Helper for plugin developers to parse a section of the config with the passed model, and replace the
         dictionary with the model object
+
         Args:
             attribute_name: the attribute holding the plugin config
             sub_config_model: the model describe the sub config
 
-        Returns: an instance of the parsed config
+        Returns:
+            an instance of the parsed config
 
         """
         config = getattr(self, attribute_name, None)
         parsed_config = sub_config_model.parse_obj(config) if config else None
         setattr(self, attribute_name, parsed_config)
         return parsed_config
 
-    def resolve_path(self, path: Path):
+    def resolve_path(self, path: Path) -> Path:
         """
         Helper function for plugin developers to resolve relative paths in config that supposed to be relative to this
         config file
 
         Args:
             path: the path to resolve
 
-        Returns: an absolute path
+        Returns:
+            an absolute path
 
         """
         root = _config_root(self.config_path)

releaseherald/releaseherald/main.py

@@ -127,7 +127,7 @@ def generate(ctx: click.Context, **kwargs):
 @click.option(
     "--config",
     type=click.Path(exists=True, dir_okay=False, path_type=Path),
-    help="Path to the config file, if not provided releaseherald.toml or pyproject.toml usde from git repo root.",
+    help="Path to the config file. If not provided, releaseherald.toml or pyproject.toml is used from git repo root.",
 )
 @click.pass_context
 def setup(

releaseherald/releaseherald/plugins/hookspecs.py

@@ -50,6 +50,7 @@ def get_command_options(command: str) -> CommandOptions:
 def on_start_command(command: str, kwargs: Dict[str, Any]):
     """
     Called before a cli command start to execute.
+
     Args:
         command: the name of the command
         kwargs: the parameters the command called with
@@ -154,6 +155,7 @@ def generate_output(
     """
     The plugin can generate an output in memory in any kind of format it want. It also has a
     chance to alter or replace an output generated by any previous plugins
+
     Args:
         version_news:
             All the version/news collected and processed by
@@ -168,6 +170,7 @@ def write_output(output: Output):
     """
     The plugin should do its final output step here. Write to file, to stdout or send a mail,
     upload to some service whatever desired.
+
     Args:
         output: the output from [generate_output][releaseherald.plugins.hookspecs.generate_output]
 

releaseherald/releaseherald/plugins/interface.py

@@ -81,6 +81,7 @@ def date(self) -> datetime.datetime:
 class News:
     """
     Represent a single newsfile
+
     Attributes:
         file_name: file name of the news fragment
         content: the content of the news file

releaseherald/releaseherald/plugins/plugin_config.py

@@ -108,6 +108,7 @@ def get_command_options(self, command: str) -> Optional[CommandOptions]:
         """
         Generate command options from Annotated fields which can be returned directly from
         [get_command_options hook][releaseherald.plugins.hookspecs.get_command_options]
+
         Args:
             command: the command these command options are registered with
 
@@ -135,6 +136,7 @@ def update(self, command: str, kwargs: Dict[str, Any]) -> None:
         """
         Update itself from commandline options, can be used in
         [on_start_command hook][releaseherald.plugins.hookspecs.on_start_command]
+
         Args:
             command: the command
             kwargs: the commandline args for the command