Browse Source

docs: keep the documentation on GitHub and retire the wiki

- Remove the Read the Docs and MkDocs configuration (.readthedocs.yml,
  mkdocs.yml, Docs/requirements.txt). The Read the Docs project belongs
  to a third party and points to a fork that no longer exists.
- Rename Docs/index.md to Docs/README.md, so that GitHub shows the
  overview when you open the Docs folder, and link the changelog and the
  license relatively.
- Move the version history and the installation steps from the wiki into
  Docs/Version-History.md and Docs/README.md. Add the notes for 4.2.5
  and 4.2.6, which the wiki never had, from the commit history.
- Describe previews and section anchors on GitHub in the contributor
  guide, and drop the changelog entry about the documentation site.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
pull/94/head
Raimund Andree 1 week ago
parent
commit
84328dc5c6
  1. 21
      .readthedocs.yml
  2. 8
      CHANGELOG.md
  3. 37
      Docs/Contributing/02-Writing.md
  4. 12
      Docs/Contributing/04-Markdown-Specifics.md
  5. 33
      Docs/README.md
  6. 152
      Docs/Version-History.md
  7. 1
      Docs/requirements.txt
  8. 11
      README.md
  9. 57
      mkdocs.yml

21
.readthedocs.yml

@ -1,21 +0,0 @@
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Required: the build image and the Python version
build:
os: ubuntu-24.04
tools:
python: "3.12"
# Build documentation with MkDocs
mkdocs:
configuration: mkdocs.yml
# Install the MkDocs version that the site is built with
python:
install:
- requirements: Docs/requirements.txt

8
CHANGELOG.md

@ -4,9 +4,7 @@ All notable changes to this project are documented in this file.
The format is based on
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Releases up to
4.2.6 are described in the
[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History)
in the wiki.
4.2.6 are described in the [version history](Docs/Version-History.md).
## [Unreleased]
@ -20,6 +18,8 @@ in the wiki.
inputs, outputs, and notes, checked against the source code
- Rewrite the home, concepts, examples, and contributor pages to match the
current cmdlets, including module settings, privileges, and long paths
- Move the version history and the installation instructions from the wiki
into the documentation, and add the missing notes for 4.2.5 and 4.2.6
### Fixed
@ -29,7 +29,5 @@ in the wiki.
`NTFSSecurity-Help.xml`
- Fix documentation examples that did not work, such as restoring
permissions from a CSV file and filtering entries by account
- Fix the documentation site navigation, the "Edit on GitHub" links, and the
Read the Docs build configuration
[Unreleased]: https://github.com/raandree/NTFSSecurity/compare/4.2.6...HEAD

37
Docs/Contributing/02-Writing.md

@ -1,24 +1,25 @@
# Write documentation
The NTFSSecurity documentation is written in Markdown and built into a
website with [MkDocs][mkdocs]. This page explains how the documentation is
organized and how to change it.
The NTFSSecurity documentation is written in Markdown and lives in the
`Docs` folder of the repository, where GitHub renders it. This page explains
how the documentation is organized and how to change it.
## Documentation structure
| Path | Content |
| --- | --- |
| `Docs/index.md` | Home page with features, requirements, and the cmdlet list |
| `Docs/README.md` | Home page with features, requirements, installation, and the cmdlet list; GitHub shows it when you open the `Docs` folder |
| `Docs/Concepts.md` | Background on security descriptors, rights, inheritance, and privileges |
| `Docs/Examples.md` | Task-oriented examples |
| `Docs/Version-History.md` | Changes in 4.2.6 and earlier |
| `Docs/Cmdlets/*.md` | One reference page per cmdlet, in platyPS format |
| `NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml` | Help file that `Get-Help` shows, generated from `Docs/Cmdlets` |
| `Docs/Contributing.md`, `Docs/Contributing/*.md` | This contributor guide |
| `mkdocs.yml` | Site settings and navigation |
| `.readthedocs.yml` | Build settings for Read the Docs |
| `README.md` | Front page of the GitHub repository |
| `CHANGELOG.md` | Changes since 4.2.6 |
When you add a page, add it to the `nav` section of `mkdocs.yml`.
When you add a page, link to it from `Docs/README.md` or from a related page,
so that readers can find it.
## Markdown editors
@ -59,8 +60,8 @@ Use Windows PowerShell 5.1 for platyPS. In PowerShell 7.4 and later,
platyPS 0.14.2 adds the `-ProgressAction` common parameter to every page.
For a new cmdlet, create the page, replace every placeholder in it, and add
the page to `mkdocs.yml`. Replace `Get-NTFSExample` with the name of the new
cmdlet:
the cmdlet to the cmdlet list in `Docs/README.md`. Replace `Get-NTFSExample`
with the name of the new cmdlet:
```powershell
New-MarkdownHelp -Command Get-NTFSExample -OutputFolder .\Docs\Cmdlets
@ -75,19 +76,12 @@ again and commit it together with the page:
New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath .\NTFSSecurity\en-US -Force
```
## Preview the website
## Preview your change
MkDocs needs Python. Install the MkDocs version that the site is built with
and start the preview server:
```powershell
pip install -r Docs/requirements.txt
mkdocs serve
```
Open `http://127.0.0.1:8000` in a browser. The preview reloads when you save
a file. Run `mkdocs build --strict` to find broken links and pages that are
missing from the navigation.
GitHub renders the pages with GitHub Flavored Markdown. To preview a page
before you push it, open it in Visual Studio Code and press **Ctrl+Shift+V**.
In a pull request, the **Files changed** tab shows a changed page rendered
when you open its menu (**...**) and select **View file**.
## Check your change
@ -132,7 +126,6 @@ workflow for larger changes in [Get started](01-Getting-Started.md).
Read the [Style guide](03-Style-Guide.md).
<!-- External URLs -->
[mkdocs]: https://www.mkdocs.org/user-guide/writing-your-docs/
[platyps]: https://github.com/PowerShell/platyPS
[label-documentation]: https://github.com/raandree/NTFSSecurity/labels/Documentation
[label-help-wanted]: https://github.com/raandree/NTFSSecurity/labels/Help%20Wanted

12
Docs/Contributing/04-Markdown-Specifics.md

@ -13,7 +13,10 @@ the additional rules for the cmdlet reference pages, which platyPS processes.
- Don't use hard tabs or trailing spaces.
- Link to other pages with relative links to the `.md` file, for example
`[Concepts](Concepts.md)` or `[Get-NTFSAccess](Cmdlets/Get-NTFSAccess.md)`.
MkDocs converts them to links to the generated pages.
GitHub renders them as links to the pages.
- Link to a section with the anchor that GitHub generates from its heading:
lowercase, with spaces replaced by hyphens and punctuation removed, for
example `[Privileges](Concepts.md#privileges)`.
- End every file with a single newline.
## Cmdlet reference pages
@ -42,10 +45,3 @@ expects:
add a sentence below each one.
- In RELATED LINKS, write each link on its own line and separate the links
with blank lines.
## MkDocs
- The site uses the built-in `readthedocs` theme.
- Every page must be listed in the `nav` section of `mkdocs.yml`.
- Files in `Docs` that aren't Markdown are copied to the website. Exclude
files that don't belong there with `exclude_docs` in `mkdocs.yml`.

33
Docs/index.md → Docs/README.md

@ -38,10 +38,26 @@ Install the module from the
Install-Module -Name NTFSSecurity
```
You can also download a release from the
[releases page](https://github.com/raandree/NTFSSecurity/releases) on GitHub.
If you have trouble, see
[How to install](https://github.com/raandree/NTFSSecurity/wiki/How-to-install).
You can also install a release without the PowerShell Gallery. Download
`NTFSSecurity.zip` from the
[releases page](https://github.com/raandree/NTFSSecurity/releases) on GitHub
and extract it into a module folder. In an elevated session, these commands
install the module for all users of Windows PowerShell 5.1 and PowerShell 7:
```powershell
Unblock-File -Path .\NTFSSecurity.zip
Expand-Archive -Path .\NTFSSecurity.zip -DestinationPath "$env:ProgramFiles\WindowsPowerShell\Modules"
```
`Unblock-File` removes the mark that Windows adds to downloaded files. If you
extract a marked zip file with File Explorer, the extracted files keep the
mark, and the execution policy `RemoteSigned` stops the module from loading.
The zip file contains the folder `NTFSSecurity`. Remove an older copy of that
folder first. To install the module only for yourself, extract it into a
folder of `$env:PSModulePath` in your profile instead, for example
`Documents\WindowsPowerShell\Modules` for Windows PowerShell 5.1 or
`Documents\PowerShell\Modules` for PowerShell 7.
## Getting started
@ -138,10 +154,8 @@ them have changed since; use the cmdlet reference for the current names.
## Version history
See the [changelog](https://github.com/raandree/NTFSSecurity/blob/master/CHANGELOG.md)
and the
[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History)
in the wiki.
See the [changelog](../CHANGELOG.md) for the changes since 4.2.6 and the
[version history](Version-History.md) for 4.2.6 and earlier.
## Contributing
@ -149,5 +163,4 @@ Contributions are welcome. See the [contributor guide](Contributing.md).
## License
NTFSSecurity is licensed under the
[MIT license](https://github.com/raandree/NTFSSecurity/blob/master/LICENSE).
NTFSSecurity is licensed under the [MIT license](../LICENSE).

152
Docs/Version-History.md

@ -0,0 +1,152 @@
# Version history
This page lists the changes in NTFSSecurity 4.2.6 and earlier. It replaces
the version history in the former GitHub wiki. For the changes since 4.2.6,
see the [changelog](../CHANGELOG.md).
## 4.2.5 and 4.2.6
The PowerShell Gallery published 4.2.5 on 2019-07-11 and 4.2.6 on
2019-07-12. The wiki listed no changes for these versions, so this list is
reconstructed from the commit history.
- Removed `Show-NTFSSimpleAccess`, which used Windows Forms, for
compatibility with PowerShell Core.
- Fixed parameter alias definitions that made importing the module fail,
for example in Service Management Automation
([#18](https://github.com/raandree/NTFSSecurity/issues/18),
[#36](https://github.com/raandree/NTFSSecurity/issues/36)).
- Fixed the `ToSimpleFileSystemAccessRule2` method of the access entries
that `Get-NTFSAccess` returns
([#48](https://github.com/raandree/NTFSSecurity/issues/48)).
- Fixed the `ApplyTo` column in the output of `Get-NTFSAccess`.
- Added the MIT license.
## 4.2.4
- Bug fixes.
## 4.2.3
- Added the cmdlet `Get-FileHash2`.
- Bug fixes.
## 4.2.1
- Added the cmdlets `Get-NTFSHardLink`, `New-NTFSHardLink`, and
`New-NTFSSymbolicLink`.
## 4.2
- Added the cmdlets `Move-Item2` and `Copy-Item2`.
- `Remove-Item2`, `Move-Item2`, and `Copy-Item2` now support `-WhatIf` and
`-Confirm`.
## 4.1
- The `-Attributes` parameter of `Get-ChildItem2` works like the one of the
standard cmdlet `Get-ChildItem`, as requested.
- `Remove-NTFSAccess` can now remove access from existing access control
entries. The old behavior is still available with the `-RemoveSpecific`
switch parameter.
## 4.0
- The `*-NTFSAccess` cmdlets can now work on security descriptors to allow
bulk processes.
- Code cleanup for better performance and maintainability.
- Bug fixes.
## 3.2.3
- Fixed a bug in `GetInheritedFrom` that resulted in "Invalid Path" or "Path
not found" errors.
## 3.2
- Bug fixes for managing auditing.
- Fixed various bugs reported on CodePlex.
## 3.1
- All cmdlets have the prefix `NTFS` now. There are aliases for backward
compatibility.
- The new version of `Get-NTFSEffectivePermission` uses `AuthzAccessCheck`
instead of `GetEffectiveRightsFromAcl`.
- The previous `Get-NTFSEffectivePermission` cmdlet has been renamed to
`Get-NTFSEffectivePermissionOld`.
- Added `FileSystemAuditRule2` to the PowerShell formatters.
- Added the `InheritedFrom` information to `FileSystemAuditRule2`.
## 3.0
- This version uses [AlphaFS](https://github.com/alphaleonis/AlphaFS) to
work around the `MAX_PATH` limit of 260 characters.
- New `*-Item2` cmdlets discover items with a long path:
- `Get-ChildItem2` (`dir2`)
- `Get-Item2` (`gi2`)
- `Remove-Item2` (`del2`, `rm2`)
- For inherited access control entries, `InheritedFrom` is displayed.
- Generic access rights are supported.
- Performance improvements.
- Bug fixes.
## 2.4
- `Remove-Access` did not remove deny entries when using the pipeline, for
example `Import-Csv .\access.txt | Remove-Access`.
- `Add-Access` did not remove deny entries when using the pipeline, for
example `Import-Csv .\access.txt | Add-Access`.
- The parameter `-Account` was undiscoverable when using the pipeline.
## 2.3
- The module now makes full use of the Backup, Restore, and Take Ownership
privileges, so as an administrator you can edit permissions on objects
that you don't have explicit access to. Privileges are enabled by default
if the value `EnablePrivileges` is `$true` in `NTFSSecurity.psd1`. The new
cmdlets `Get-Privileges`, `Disable-Privileges`, and `Enable-Privileges`
are for manual control.
- The `-Path` parameter now works consistently.
## 2.1
- Fixed bugs with `Set-Owner`.
- Added support for managing auditing (SACL).
## 2.0 (beta)
- New commands: `Get-SimpleAccess`, `Get-SimpleEffectiveAccess`,
`Show-SimpleAccess`, `Show-SimpleEffectiveAccess`, and `Copy-Access`.
- All cmdlets are now written in C#.
- Fixed a number of bugs.
## 1.3
- Fixed an issue with parameter handling.
- Now works with PowerShell 3.0.
## 1.2
- Fixed some issues with path validation.
- Fixed documentation bugs.
## 1.1
- Fixed the issue with square brackets in paths.
- Performance improvements.
## 1.0
- The last tests didn't reveal any issue. PowerShell has a problem handling
files that have square brackets in the file name, and this module inherits
the issue.
## 0.9 (beta)
- Fixed some bugs.
- Updated documentation.
## 0.8 (beta)
- Initial release.

1
Docs/requirements.txt

@ -1 +0,0 @@
mkdocs==1.6.1

11
README.md

@ -18,9 +18,9 @@ Install-Module -Name NTFSSecurity
```
You can also download a release from the
[releases page](https://github.com/raandree/NTFSSecurity/releases). If you
have trouble, see
[How to install](https://github.com/raandree/NTFSSecurity/wiki/How-to-install).
[releases page](https://github.com/raandree/NTFSSecurity/releases) and
install it without the PowerShell Gallery; see
[Installation](Docs/README.md#installation).
The module runs on Windows in Windows PowerShell 5.1 and PowerShell 7.
@ -43,7 +43,7 @@ Get-ChildItem2 -Path C:\Data -Recurse | Get-NTFSAccess -ExcludeInherited
## Documentation
- [Overview](Docs/index.md): features, requirements, and the list of cmdlets
- [Overview](Docs/README.md): features, requirements, and the list of cmdlets
- [Concepts](Docs/Concepts.md): security descriptors, access rights,
inheritance, privileges, long paths, and module settings
- [Examples](Docs/Examples.md): common tasks
@ -59,8 +59,7 @@ although some cmdlet names have changed since:
## Version history
See [CHANGELOG.md](CHANGELOG.md) for changes since version 4.2.6 and the
[version history](https://github.com/raandree/NTFSSecurity/wiki/Version-History)
in the wiki for earlier releases.
[version history](Docs/Version-History.md) for 4.2.6 and earlier releases.
## License

57
mkdocs.yml

@ -1,57 +0,0 @@
copyright: "The NTFSSecurity module is licensed under the <a href='https://github.com/raandree/NTFSSecurity/blob/master/LICENSE'>MIT license</a>."
repo_url: https://github.com/raandree/NTFSSecurity
edit_uri: edit/master/Docs/
nav:
- Home: ./index.md
- Concepts: ./Concepts.md
- Examples: ./Examples.md
- Cmdlets:
- Add-NTFSAccess: Cmdlets/Add-NTFSAccess.md
- Add-NTFSAudit: Cmdlets/Add-NTFSAudit.md
- Clear-NTFSAccess: Cmdlets/Clear-NTFSAccess.md
- Clear-NTFSAudit: Cmdlets/Clear-NTFSAudit.md
- Copy-Item2: Cmdlets/Copy-Item2.md
- Disable-NTFSAccessInheritance: Cmdlets/Disable-NTFSAccessInheritance.md
- Disable-NTFSAuditInheritance: Cmdlets/Disable-NTFSAuditInheritance.md
- Disable-Privileges: Cmdlets/Disable-Privileges.md
- Enable-NTFSAccessInheritance: Cmdlets/Enable-NTFSAccessInheritance.md
- Enable-NTFSAuditInheritance: Cmdlets/Enable-NTFSAuditInheritance.md
- Enable-Privileges: Cmdlets/Enable-Privileges.md
- Get-ChildItem2: Cmdlets/Get-ChildItem2.md
- Get-DiskSpace: Cmdlets/Get-DiskSpace.md
- Get-FileHash2: Cmdlets/Get-FileHash2.md
- Get-Item2: Cmdlets/Get-Item2.md
- Get-NTFSAccess: Cmdlets/Get-NTFSAccess.md
- Get-NTFSAudit: Cmdlets/Get-NTFSAudit.md
- Get-NTFSEffectiveAccess: Cmdlets/Get-NTFSEffectiveAccess.md
- Get-NTFSHardLink: Cmdlets/Get-NTFSHardLink.md
- Get-NTFSInheritance: Cmdlets/Get-NTFSInheritance.md
- Get-NTFSOrphanedAccess: Cmdlets/Get-NTFSOrphanedAccess.md
- Get-NTFSOrphanedAudit: Cmdlets/Get-NTFSOrphanedAudit.md
- Get-NTFSOwner: Cmdlets/Get-NTFSOwner.md
- Get-NTFSSecurityDescriptor: Cmdlets/Get-NTFSSecurityDescriptor.md
- Get-NTFSSimpleAccess: Cmdlets/Get-NTFSSimpleAccess.md
- Get-Privileges: Cmdlets/Get-Privileges.md
- Move-Item2: Cmdlets/Move-Item2.md
- New-NTFSHardLink: Cmdlets/New-NTFSHardLink.md
- New-NTFSSymbolicLink: Cmdlets/New-NTFSSymbolicLink.md
- Remove-Item2: Cmdlets/Remove-Item2.md
- Remove-NTFSAccess: Cmdlets/Remove-NTFSAccess.md
- Remove-NTFSAudit: Cmdlets/Remove-NTFSAudit.md
- Set-NTFSInheritance: Cmdlets/Set-NTFSInheritance.md
- Set-NTFSOwner: Cmdlets/Set-NTFSOwner.md
- Set-NTFSSecurityDescriptor: Cmdlets/Set-NTFSSecurityDescriptor.md
- Test-Path2: Cmdlets/Test-Path2.md
- Contributing:
- Overview: Contributing.md
- Getting Started: Contributing/01-Getting-Started.md
- Writing: Contributing/02-Writing.md
- Style Guide: Contributing/03-Style-Guide.md
- Markdown Specifics: Contributing/04-Markdown-Specifics.md
site_name: NTFSSecurity
site_description: PowerShell module for managing NTFS permissions, auditing, inheritance, and ownership
theme: readthedocs
site_author: Raimund Andrée, James Smith
docs_dir: ./Docs
exclude_docs: |
/requirements.txt
Loading…
Cancel
Save