CLI Support and changes to make PowerDocu more friendly for usage with DevOps #111

a1dancole · 2023-06-01T10:57:03Z

Change Documenter projects to be Library types instead of Console to avoid confusion in how to interact with the projects following this change.

Add a new Console application PowerDocu.CLI to define the entry point for use in the command line. This change also includes support for all available variables that are possible in the GUI with validation.

I see this proposed change as the start of making PowerDocu available in DevOps by providing a clearly defined, documented CLI interface. I will be using these proposed changes to start working on making PowerDocu available in Azure DevOps as I want to integrate it with existing pipelines that I currently use

Introduce support for all variables in the front-end and add in console validation.

a1dancole · 2023-06-01T10:58:24Z

PowerDocu.SolutionDocumenter/SolutionDocumentationContent.cs

@@ -3,7 +3,7 @@

 namespace PowerDocu.SolutionDocumenter
 {
-    class SolutionDocumentationContent
+    public class SolutionDocumentationContent


This access modifier was causing me build issues

modery · 2023-06-03T08:35:28Z

Hi Aidan, many thanks for this! Wanted to look into this at some point "soon" as well, this helps a lot. Will review it in detail in the upcoming days

a1dancole · 2023-06-05T09:44:16Z

Hi Rene, my pleasure. Thank you for creating this awesome tool!

There's a consideration that might be worth exploring which is why I haven't marked this PR as Ready for review.

The CLI support can be added to the GUI app by taking advantage of Main and args variable Main() and command-line arguments
to remove the two entry points to the application and combine into one.

…te documentation to specific folders

…nd introducing a .order file at the route of the documentation. This allows documentation to be source controlled and viewable in DevOps wiki

Add support for devops wiki by changing the folder structure format …

a1dancole · 2023-06-09T16:07:52Z

Just some updates on this PR as well as on Azure DevOps

I made some additional changes to the CLI project, introduced an output variable and made some changes to the solution output so that it can be used in DevOps wiki's. The naming conventions didn't work with DevOps wiki, even with a .order file. There also needed to be the generation of a .order file to allow DevOps wiki's to understand the multiple levels in solution documentation.

I've also successfully created an Azure DevOps custom task PowerDocu-DevOps that downloads a the release of PowerDocu to the agent from GitHub and accepts all of the CLI arguments as part of the PR and executes PowerDocu. It's currently a private project being executed in our own Pipelines but is so far successful. I'm happy to share access to the task on Marketplace.

How it looks in DevOps:

Our pipelines source control our solutions, but by setting the output folder we're able to separate out the solution from the documentation

Then by using Azure DevOps 'Publish code as wiki' we're able to create a wiki page from the repository

a1dancole · 2023-06-09T16:09:25Z

PowerDocu.AppDocumenter/AppDocumentationContent.cs

@@ -24,7 +24,7 @@ class AppDocumentationContent
        public AppDocumentationContent(AppEntity app, string path)
        {
            NotificationHelper.SendNotification("Preparing documentation content for " + app.Name);
-            folderPath = path + CharsetHelper.GetSafeName(@"\AppDoc - " + app.Name + @"\");
+            folderPath = path + CharsetHelper.GetSafeName(@"\AppDoc " + app.Name + @"\");


The '-' is read in DevOps Wiki's as a space, which got the wiki structure very confused so this had to be removed

a1dancole · 2023-06-09T16:11:34Z

PowerDocu.AppDocumenter/AppDocumentationGenerator.cs

@@ -10,21 +10,22 @@ namespace PowerDocu.AppDocumenter
 {
    public static class AppDocumentationGenerator
    {
-        public static List<AppEntity> GenerateDocumentation(string filePath, string fileFormat, bool documentDefaultChangesOnly, bool documentDefaults, string wordTemplate = null)
+        public static List<AppEntity> GenerateDocumentation(string filePath, string fileFormat, bool documentDefaultChangesOnly, bool documentDefaults, string wordTemplate = null, string outputPath = null)


Add support for a different path to save the documentation to so that in a DevOps pipeline the documentation can be created in a specific folder on an agent and then commited to the repository.

It becomes hard to extract the documentation out when it's being saved in the folder that the solution is so this is a quality of life feature

a1dancole · 2023-06-09T16:12:11Z

PowerDocu.FlowDocumenter/FlowDocumentationContent.cs

@@ -19,7 +19,7 @@ class FlowDocumentationContent
        public FlowDocumentationContent(FlowEntity flow, string path, FlowActionSortOrder sortOrder = FlowActionSortOrder.SortByName)
        {
            NotificationHelper.SendNotification("Preparing documentation content for " + flow.Name);
-            folderPath = path + CharsetHelper.GetSafeName(@"\FlowDoc - " + flow.Name + @"\");
+            folderPath = path + CharsetHelper.GetSafeName(@"\FlowDoc " + flow.Name + @"\");


The '-' is read in DevOps Wiki's as a space, which got the wiki structure very confused so this had to be removed

a1dancole · 2023-06-09T16:12:30Z

PowerDocu.FlowDocumenter/FlowDocumentationGenerator.cs

@@ -7,21 +7,22 @@ namespace PowerDocu.FlowDocumenter
 {
    public static class FlowDocumentationGenerator
    {
-        public static List<FlowEntity> GenerateDocumentation(string filePath, string fileFormat, string flowActionSortOrder, string wordTemplate = null)
+        public static List<FlowEntity> GenerateDocumentation(string filePath, string fileFormat, string flowActionSortOrder, string wordTemplate = null, string outputPath = null)


Add support for a different path to save the documentation to so that in a DevOps pipeline the documentation can be created in a specific folder on an agent and then commited to the repository.

It becomes hard to extract the documentation out when it's being saved in the folder that the solution is so this is a quality of life feature

a1dancole · 2023-06-09T16:12:41Z

PowerDocu.SolutionDocumenter/SolutionDocumentationGenerator.cs

@@ -9,7 +9,7 @@ namespace PowerDocu.SolutionDocumenter
 {
    public static class SolutionDocumentationGenerator
    {
-        public static void GenerateDocumentation(string filePath, string fileFormat, bool documentDefaultChangesOnly, bool documentDefaults, string flowActionSortOrder, string wordTemplate = null)
+        public static void GenerateDocumentation(string filePath, string fileFormat, bool documentDefaultChangesOnly, bool documentDefaults, string flowActionSortOrder, string wordTemplate = null, string outputPath = null)


Add support for a different path to save the documentation to so that in a DevOps pipeline the documentation can be created in a specific folder on an agent and then commited to the repository.

It becomes hard to extract the documentation out when it's being saved in the folder that the solution is so this is a quality of life feature

a1dancole · 2023-06-09T16:13:48Z

PowerDocu.SolutionDocumenter/SolutionMarkdownBuilder.cs

@@ -322,5 +322,19 @@ private MdImageSpan getAccessLevelIcon(string accessLevel)
            };
            return getAccessLevelIcon(level);
        }
+
+        private void createOrderFile()


This order file is needed to allow DevOps wiki to understand the folder structure of a solution's documentation

Wiki files and file structure

…lder paths

…rect stdout correctly.

keinMEME · 2023-11-27T12:40:18Z

Hi guys,
this feature looks very good.
Is a new official release version planned?

modery · 2024-01-31T08:32:18Z

Hi @a1dancole , finally came back to PowerDocu and continued working on it. Your PRs have all been requested, and I'm about to release a new version overall in the next few days.
Do you want to add a bit of documentation on the functionality you added here?

Refactor CLI support to a common Console project.

922131a

Introduce support for all variables in the front-end and add in console validation.

a1dancole commented Jun 1, 2023

View reviewed changes

Aidan Cole added 2 commits June 1, 2023 12:09

Check file exists before trying to process

a4e712f

Rudimentary error handling

56e4ee7

Aidan Cole and others added 6 commits June 7, 2023 16:11

Add support for latest version check

60520a5

Correction to CLI options

86e73ff

Add support for OutputPath parameter to allow DevOps pipelines to wri…

4f918c4

…te documentation to specific folders

Merge branch 'modery:main' into main

de23237

Add support for devops wiki by changing the folder structure format a…

f0799c7

…nd introducing a .order file at the route of the documentation. This allows documentation to be source controlled and viewable in DevOps wiki

Merge pull request #1 from a1dancole/DevOps-Wiki

028778a

Add support for devops wiki by changing the folder structure format …

a1dancole commented Jun 9, 2023

View reviewed changes

Aidan Cole added 2 commits June 15, 2023 21:24

Correct some mistakes in folder path, also fixes image genereation fo…

16eaa5d

…lder paths

Move CLI support to .GUI project add checks for WIndows & Linux to di…

44c22dd

…rect stdout correctly.

a1dancole marked this pull request as ready for review June 15, 2023 20:57

a1dancole changed the title ~~Refactor CLI support to a common Console project.~~ CLI Support and changes to make PowerDocu more friendly for usage with DevOps Jun 15, 2023

Aidan Cole added 2 commits June 16, 2023 10:37

Static analysis warning fixes

b2da5a6

Will not be null as was checked further up

977232d

modery merged commit 7c8ff37 into modery:main Jan 30, 2024

modery mentioned this pull request Feb 13, 2024

FR - Executable via comand Line #88

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Support and changes to make PowerDocu more friendly for usage with DevOps #111

CLI Support and changes to make PowerDocu more friendly for usage with DevOps #111

a1dancole commented Jun 1, 2023

a1dancole Jun 1, 2023

a1dancole Jun 1, 2023

modery commented Jun 3, 2023

a1dancole commented Jun 5, 2023

a1dancole commented Jun 9, 2023

a1dancole Jun 9, 2023

a1dancole Jun 9, 2023

a1dancole Jun 9, 2023

a1dancole Jun 9, 2023

a1dancole Jun 9, 2023

a1dancole Jun 9, 2023

keinMEME commented Nov 27, 2023

modery commented Jan 31, 2024

CLI Support and changes to make PowerDocu more friendly for usage with DevOps #111

CLI Support and changes to make PowerDocu more friendly for usage with DevOps #111

Conversation

a1dancole commented Jun 1, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

modery commented Jun 3, 2023

a1dancole commented Jun 5, 2023

a1dancole commented Jun 9, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

keinMEME commented Nov 27, 2023

modery commented Jan 31, 2024