Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix XML documentation generation and add Markdown docs to VS solution #315

Closed
wants to merge 7 commits into from
Closed

Fix XML documentation generation and add Markdown docs to VS solution #315

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0609205
Bringing docs into the solution and fixing xml document paths
Oct 14, 2017
39b4559
Fixing xml docs by using global property 'GenerateDocumentationFile' …
Oct 17, 2017
57a10b4
Merge branch 'xml-docs-fix' into harmonising-core-and-windsor-2
Oct 17, 2017
c71dbff
Reformat of common.props
Oct 17, 2017
f40c170
Cleaned up gitignore file
Nov 24, 2017
e4485ac
Bumping dotnet core to try and make travis ci build pass
Nov 24, 2017
8ef9eec
Fixed conflict so we can merge docs
Jan 6, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,10 @@ project.lock.json
/.dotnet/
tools/**/obj/
tools/**/build/

# Docs artifacts
docs/obj/
docs/bin/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should just ignore obj and bin directories everywhere, we've got 4 sets of these patterns now.


# Xml doc/test files
*.xml
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think ignoring all XML files everywhere is a good idea, this isn't needed anymore anyway.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mind you, this is only the root folder. It also prevents DesktopClrTestResults.xml and NetCoreClrTestResults.xml from being unstaged and accidentally committed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mind you, this is only the root folder. It also prevents DesktopClrTestResults.xml and NetCoreClrTestResults.xml from being unstaged and accidentally committed.

@Fir3pho3nixx I think you misunderstand how gitignores work, sorry for this pull request being death by a thousand cuts.

If the pattern does not contain a slash /, Git treats it as a shell glob pattern and checks for a match against the pathname relative to the location of the .gitignore file (relative to the toplevel of the work tree if not from a .gitignore file).

If the pattern ends with a slash, it is removed for the purpose of the following description, but it would only find a match with a directory. In other words, foo/ will match a directory foo and paths underneath it, but will not match a regular file or a symbolic link foo (this is consistent with the way how pathspec works in general in Git).

A leading slash matches the beginning of the pathname. For example, "/*.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c".

(https://git-scm.com/docs/gitignore)

*.xml is a glob pattern across all directories (like the *.suo pattern), it would need to be /*.xml to just match the root.

There is also no need for the **, you can just do bin/ to match the directory rather the contents.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okiday, I checked the globs by running git status and it appeared to be OK. Will fix.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cheers, I know I'm a nitpicking bastard 😉

P.S. this PR now also conflicts because of another PR I merged earlier.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't worry I will sort that.

Copy link
Author

@ghost ghost Jan 6, 2018 •
edited by ghost
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jonorossi - I think I misled you earlier when I said the XML artifacts are only in the root.

I cleaned the project, using git clean -x -f -d, then changed the .gitignore to have a leading slash in front of the *.xml -> /*.xml.

After running a full build and tests, I then double checked using git status with the following result.

Your branch is up-to-date with 'origin/harmonising-core-and-windsor-2'.

All conflicts fixed but you are still merging.
  (use "git commit" to conclude merge)

Changes to be committed:

        modified:   CHANGELOG.md
        modified:   src/Castle.Services.Logging.log4netIntegration/Castle.Services.Logging.log4netIntegration.csproj

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   .gitignore
        modified:   Castle.Core.sln.DotSettings

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        src/Castle.Services.Logging.log4netIntegration/Castle.Services.Logging.Log4netIntegration.xml

Notice how git thinks it needs to add the xml build artifact from the Log4netIntegration?

I believe my original approach is correct because this is a build artifact. It was my fault for not being clear on this in the first place but I do test my work before committing(admittedly I don't always test it on linux hence the previous casing issue). I am also puzzled as to why the casing issue cropped up and was not detected by Travis. Bizarre.

The globbing pattern I thought would be OK because of this:

Two consecutive asterisks ("**") in patterns matched against full pathname may have special meaning:

A leading "**" followed by a slash means match in all directories. For example, "**/foo" matches file or directory "foo" anywhere, the same as pattern "foo". "**/foo/bar" matches file or directory "bar" anywhere that is directly under directory "foo". <- !! Why I put the glob on the front of bin/obj. !!

A trailing "/**" matches everything inside. For example, "abc/**" matches all files inside directory "abc", relative to the location of the .gitignore file, with infinite depth. <- !! Why I put the glob on the end !!

A slash followed by two consecutive asterisks then a slash matches zero or more directories. For example, "a/**/b" matches "a/b", "a/x/b", "a/x/y/b" and so on.

Other consecutive asterisks are considered invalid.

You might consider it unnecessary although it is still valid. I just failed to explain myself perhaps properly.

If none of this is good for you, my alternative is to close out the PR. I am done wasting time on this.

14 changes: 13 additions & 1 deletion Castle.Core.sln
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio 15
VisualStudioVersion = 15.0.26403.7
VisualStudioVersion = 15.0.26730.16
MinimumVisualStudioVersion = 10.0.40219.1
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Castle Build", "Castle Build", "{1B999D24-B7AB-4997-96E7-08FA05325694}"
ProjectSection(SolutionItems) = preProject
Expand Down Expand Up @@ -31,6 +31,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Castle.Services.Logging.Ser
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Castle Services", "Castle Services", "{A598EE9B-41CE-4BE8-BF93-2C91F919F97E}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Castle Docs", "Castle Docs", "{EC3FDC8C-1D6C-49DA-AD19-E1521A75728E}"
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Documentation", "docs\Documentation.csproj", "{5F7AA0D3-FE16-40BD-9492-7B8BD509FD57}"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new tooling allows project files to support wildcards, do solution files not support wildcards for files?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be great if they sorted solution files out, but I have not come across anything that allows that behaviour in VS latest.

Nothing here either

EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Expand Down Expand Up @@ -61,6 +65,10 @@ Global
{91B2A82F-63F6-46B1-8EDC-5D029BCF6A2B}.Debug|Any CPU.Build.0 = Debug|Any CPU
{91B2A82F-63F6-46B1-8EDC-5D029BCF6A2B}.Release|Any CPU.ActiveCfg = Release|Any CPU
{91B2A82F-63F6-46B1-8EDC-5D029BCF6A2B}.Release|Any CPU.Build.0 = Release|Any CPU
{5F7AA0D3-FE16-40BD-9492-7B8BD509FD57}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{5F7AA0D3-FE16-40BD-9492-7B8BD509FD57}.Debug|Any CPU.Build.0 = Debug|Any CPU
{5F7AA0D3-FE16-40BD-9492-7B8BD509FD57}.Release|Any CPU.ActiveCfg = Release|Any CPU
{5F7AA0D3-FE16-40BD-9492-7B8BD509FD57}.Release|Any CPU.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
Expand All @@ -70,5 +78,9 @@ Global
{AFD3B071-E971-499B-A95B-E98155EB66E8} = {A598EE9B-41CE-4BE8-BF93-2C91F919F97E}
{344D907D-6641-4A61-94C2-4980B5804FE2} = {A598EE9B-41CE-4BE8-BF93-2C91F919F97E}
{91B2A82F-63F6-46B1-8EDC-5D029BCF6A2B} = {A598EE9B-41CE-4BE8-BF93-2C91F919F97E}
{5F7AA0D3-FE16-40BD-9492-7B8BD509FD57} = {EC3FDC8C-1D6C-49DA-AD19-E1521A75728E}
EndGlobalSection
GlobalSection(ExtensibilityGlobals) = postSolution
SolutionGuid = {DCC946F8-F280-429F-88A5-4168202813BF}
EndGlobalSection
EndGlobal
1 change: 1 addition & 0 deletions buildscripts/build.cmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ GOTO restore_packages

:restore_packages
dotnet restore ./tools/Explicit.NuGet.Versions/Explicit.NuGet.Versions.csproj
dotnet restore ./docs/Documentation.csproj
dotnet restore ./buildscripts/BuildScripts.csproj
dotnet restore ./src/Castle.Core/Castle.Core.csproj
dotnet restore ./src/Castle.Core.Tests/Castle.Core.Tests.csproj
Expand Down
5 changes: 3 additions & 2 deletions buildscripts/common.props
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
<Project>

<PropertyGroup>
<NoWarn>$(NoWarn);CS1591;CS3014;CS3003;CS3001;CS3021</NoWarn>
<RepositoryType>git</RepositoryType>
<RepositoryUrl>https://github.com/castleproject/Core</RepositoryUrl>
<BuildVersion>0.0.0</BuildVersion>
<BuildVersion Condition="'$(APPVEYOR_BUILD_VERSION)'!=''">$(APPVEYOR_BUILD_VERSION)</BuildVersion>
<BuildVersionMajor>$(BuildVersion.Split('.')[0])</BuildVersionMajor>
<AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
<AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup>
Expand Down
12 changes: 12 additions & 0 deletions docs/Documentation.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<TargetFrameworks>net461</TargetFrameworks>
</PropertyGroup>

<PropertyGroup>
<SignAssembly>False</SignAssembly>
<GeneratePackageOnBuild>False</GeneratePackageOnBuild>
</PropertyGroup>

</Project>
1 change: 0 additions & 1 deletion src/Castle.Core/Castle.Core.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@
<PublicSign Condition="'$(OS)'=='Unix'">true</PublicSign>
<FrameworkPathOverride Condition="'$(OS)'=='Unix'">$(NuGetPackageFolders)microsoft.targetingpack.netframework.v4.6.1\1.0.1\lib\net461\</FrameworkPathOverride>
<PackageTags>castle dynamicproxy dynamic proxy dynamicproxy2 dictionaryadapter emailsender</PackageTags>
<DocumentationFile>$(OutputPath)Castle.Core.xml</DocumentationFile>
</PropertyGroup>

<ItemGroup>
Expand Down
1 change: 0 additions & 1 deletion src/Castle.Services.Logging.NLogIntegration/Castle.Services.Logging.NLogIntegration.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@
<PublicSign Condition="'$(OS)'=='Unix'">true</PublicSign>
<FrameworkPathOverride Condition="'$(OS)'=='Unix'">$(NuGetPackageFolders)microsoft.targetingpack.netframework.v4.6.1\1.0.1\lib\net461\</FrameworkPathOverride>
<PackageTags>castle logging NLog</PackageTags>
<DocumentationFile>$(OutputPath)Castle.Services.Logging.NLogIntegration.xml</DocumentationFile>
</PropertyGroup>

<ItemGroup Condition="'$(TargetFramework)'=='netstandard1.3'">
Expand Down
1 change: 0 additions & 1 deletion ...tle.Services.Logging.SerilogIntegration/Castle.Services.Logging.SerilogIntegration.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@
<PublicSign Condition="'$(OS)'=='Unix'">true</PublicSign>
<FrameworkPathOverride Condition="'$(OS)'=='Unix'">$(NuGetPackageFolders)microsoft.targetingpack.netframework.v4.6.1\1.0.1\lib\net461\</FrameworkPathOverride>
<PackageTags>castle logging serilog</PackageTags>
<DocumentationFile>$(OutputPath)Castle.Services.Logging.SerilogIntegration.xml</DocumentationFile>
</PropertyGroup>

<ItemGroup Condition="'$(TargetFramework)'=='netstandard1.3'">
Expand Down
1 change: 0 additions & 1 deletion ...tle.Services.Logging.log4netIntegration/Castle.Services.Logging.log4netIntegration.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@
<PublicSign Condition="'$(OS)'=='Unix'">true</PublicSign>
<FrameworkPathOverride Condition="'$(OS)'=='Unix'">$(NuGetPackageFolders)microsoft.targetingpack.netframework.v4.6.1\1.0.1\lib\net461\</FrameworkPathOverride>
<PackageTags>castle logging log4net</PackageTags>
<DocumentationFile>$(OutputPath)Castle.Services.Logging.log4netIntegration.xml</DocumentationFile>
</PropertyGroup>

<ItemGroup Condition="'$(TargetFramework)'=='net35'OR'$(TargetFramework)'=='net40'OR'$(TargetFramework)'=='net45'">
Expand Down