You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Write-Warning"Skipping ReadTheDocs manifest file creation as it already exists. Please remove the following file if you want it to be regenerated: $YMLFile"
679
+
Write-Warning'The mkdocs.yml file already exists. If you want this regenerated you will need to delete it first.'
Copy file name to clipboardExpand all lines: build/docs/ReadTheDocs/Introduction/Introduction.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ Firstly, this module uses everything it creates in its own build process. Since
19
19
20
20
Aside from the handful of helper functions there is an included 'plaster' folder that includes a customized version of the module of the same name and a manifest folder named ModuleBuild. This ModuleBuild folder contains a scaffold directory structure used to create your projects. The questions asked as well as the actions taken when copying over the scaffold folder items are both contained in the root of the plaster directory in 'plastercontent.ps1' and 'plasterparameters.ps1' and are made into the plaster manifest file at build time.
21
21
22
-
The scaffolding itself is mostly a big invoke-build script and does not need the ModuleBuild module to perform build tasks.
22
+
The scaffolding itself is mostly a big invoke-build script and does not need the ModuleBuild loaded to perform build tasks.
23
23
24
24
## Folder Structure
25
25
A default ModuleBuild project scaffold will look like the following for a project named 'ModuleName' with build version 0.0.1 sucessfully built.
Copy file name to clipboardExpand all lines: build/docs/ReadTheDocs/Usage/7 - Project Documentation.md
+13-5Lines changed: 13 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ Keeping documentation updated for your project comes in two forms with the modul
6
6
7
7
Your module documentation also comes in a few different forms and locations that are important to know ahead of time.
8
8
9
-
1.**Project documentation** - This is the docs folder at the root of your project. This is fully generated from your build/docs folder at each build. Also, your function documentation gets dropped in here.
9
+
1.**Project documentation** - This is the docs folder at the root of your project. This is fully generated from your build\docs folder and automatically from PlatyPS at each build.
10
10
2.**Module documentation (distributed)** - This is packaged within your module release docs folder. This is essentially just a trimmed down version of your project documentation that only includes your module function documentation and little else. This is used to create your downloadable documentation (a cab file) and is also used as a point in time documentation for specific versions of your module.
11
11
3.**Module documentation (downloadable)** - This is distributed with the module in the en-US folder and includes the local cab/zip/xml files for local module help.
12
12
@@ -45,11 +45,19 @@ If you have a large project with little CBH this can be a good way to kickstart
45
45
46
46
>**NOTE:** This process requires you to copy the resulting files back into your project to be of any use.
47
47
48
-
## ReadTheDocs.net Integration
49
-
If you have enabled readthedocs.net integration in the ModuleBuild configuration then a mkdocs.yml file will get updated automatically at the root of your project directory. It is up to you to setup the integration between your github.com account and readthedocs.net for this to be of any use in your project. When setting up your project at the ReadTheDocs website remember to set the advanced settings for 'mkdocs' processing.
48
+
## Generic Documentation
49
+
Most of your documentation will come from two sources, the auto-generated function markdown that PlatyPS spits out and the build\docs\Additional folder.
50
50
51
-
The ReadTheDocs manifest file gets generated from the folder structure in .\build\docs\ReadTheDocs. Each subfolder becomes a category with each markdown document within becoming a specific page within it.
51
+
## ReadTheDocs.org Integration
52
+
If you have enabled readthedocs.org integration in the ModuleBuild configuration then a mkdocs.yml file will get updated automatically at the root of your project directory. It is up to you to setup the integration between your github.com account and readthedocs.org for this to be of any use in your project. When setting up your project at the ReadTheDocs website remember to set the advanced settings for 'mkdocs' processing.
53
+
54
+
### ReadTheDocs YAML Configuration
55
+
The ReadTheDocs manifest file gets generated from three locations:
56
+
57
+
1. The folder structure in .\build\docs\ReadTheDocs - Each subfolder becomes a category with each markdown document within becoming a specific page within it.
58
+
2. The markdown files in .\build\docs\Additional - Each file is placed at the root of your pages section in the finished yaml file.
59
+
3. Markdown files auto-generated by PlatyPS for each function. These get copied over to docs\Functions at every build.
52
60
53
61
Beware that the order of the pages in this manifest file can be rather random. You will want to update the file to suit your needs (and then possibly disable readthedocs integration within your ModuleBuild config file so it doesn't revert the next build you run).
54
62
55
-
**mkdocs.yml needs to be manually removed if you want it to be regenerated**
63
+
**mkdocs.yml needs to be manually removed if you want it to be entirely regenerated**
Copy file name to clipboardExpand all lines: docs/Introduction/Introduction.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,7 +19,7 @@ Firstly, this module uses everything it creates in its own build process. Since
19
19
20
20
Aside from the handful of helper functions there is an included 'plaster' folder that includes a customized version of the module of the same name and a manifest folder named ModuleBuild. This ModuleBuild folder contains a scaffold directory structure used to create your projects. The questions asked as well as the actions taken when copying over the scaffold folder items are both contained in the root of the plaster directory in 'plastercontent.ps1' and 'plasterparameters.ps1' and are made into the plaster manifest file at build time.
21
21
22
-
The scaffolding itself is mostly a big invoke-build script and does not need the ModuleBuild module to perform build tasks.
22
+
The scaffolding itself is mostly a big invoke-build script and does not need the ModuleBuild loaded to perform build tasks.
23
23
24
24
## Folder Structure
25
25
A default ModuleBuild project scaffold will look like the following for a project named 'ModuleName' with build version 0.0.1 sucessfully built.
Copy file name to clipboardExpand all lines: docs/Usage/7 - Project Documentation.md
+13-5Lines changed: 13 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ Keeping documentation updated for your project comes in two forms with the modul
6
6
7
7
Your module documentation also comes in a few different forms and locations that are important to know ahead of time.
8
8
9
-
1.**Project documentation** - This is the docs folder at the root of your project. This is fully generated from your build/docs folder at each build. Also, your function documentation gets dropped in here.
9
+
1.**Project documentation** - This is the docs folder at the root of your project. This is fully generated from your build\docs folder and automatically from PlatyPS at each build.
10
10
2.**Module documentation (distributed)** - This is packaged within your module release docs folder. This is essentially just a trimmed down version of your project documentation that only includes your module function documentation and little else. This is used to create your downloadable documentation (a cab file) and is also used as a point in time documentation for specific versions of your module.
11
11
3.**Module documentation (downloadable)** - This is distributed with the module in the en-US folder and includes the local cab/zip/xml files for local module help.
12
12
@@ -45,11 +45,19 @@ If you have a large project with little CBH this can be a good way to kickstart
45
45
46
46
>**NOTE:** This process requires you to copy the resulting files back into your project to be of any use.
47
47
48
-
## ReadTheDocs.net Integration
49
-
If you have enabled readthedocs.net integration in the ModuleBuild configuration then a mkdocs.yml file will get updated automatically at the root of your project directory. It is up to you to setup the integration between your github.com account and readthedocs.net for this to be of any use in your project. When setting up your project at the ReadTheDocs website remember to set the advanced settings for 'mkdocs' processing.
48
+
## Generic Documentation
49
+
Most of your documentation will come from two sources, the auto-generated function markdown that PlatyPS spits out and the build\docs\Additional folder.
50
50
51
-
The ReadTheDocs manifest file gets generated from the folder structure in .\build\docs\ReadTheDocs. Each subfolder becomes a category with each markdown document within becoming a specific page within it.
51
+
## ReadTheDocs.org Integration
52
+
If you have enabled readthedocs.org integration in the ModuleBuild configuration then a mkdocs.yml file will get updated automatically at the root of your project directory. It is up to you to setup the integration between your github.com account and readthedocs.org for this to be of any use in your project. When setting up your project at the ReadTheDocs website remember to set the advanced settings for 'mkdocs' processing.
53
+
54
+
### ReadTheDocs YAML Configuration
55
+
The ReadTheDocs manifest file gets generated from three locations:
56
+
57
+
1. The folder structure in .\build\docs\ReadTheDocs - Each subfolder becomes a category with each markdown document within becoming a specific page within it.
58
+
2. The markdown files in .\build\docs\Additional - Each file is placed at the root of your pages section in the finished yaml file.
59
+
3. Markdown files auto-generated by PlatyPS for each function. These get copied over to docs\Functions at every build.
52
60
53
61
Beware that the order of the pages in this manifest file can be rather random. You will want to update the file to suit your needs (and then possibly disable readthedocs integration within your ModuleBuild config file so it doesn't revert the next build you run).
54
62
55
-
**mkdocs.yml needs to be manually removed if you want it to be regenerated**
63
+
**mkdocs.yml needs to be manually removed if you want it to be entirely regenerated**
0 commit comments