Skip to content

Commit

Permalink
merge master
Browse files Browse the repository at this point in the history
  • Loading branch information
@jackfoxy
jackfoxy committed Jun 10, 2017
1 parent 4e384b9 commit 265feb0
Show file tree
Hide file tree
Showing 11 changed files with 28 additions and 66 deletions.
12 changes: 3 additions & 9 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -169,12 +169,6 @@ $RECYCLE.BIN/
# NuGet Packages Directory
packages/

# Generated documentation folder
docs/output/

# Temp folder used for publishing docs
temp/

# Test results produced by build
TestResults.xml

Expand All @@ -186,7 +180,7 @@ localpackages/
paket-files
*.orig
.paket/paket.exe
docs/content/license.md
docs/content/release-notes.md
docsraw/content/license.md
docsraw/content/release-notes.md
.fake
docs/tools/FSharp.Formatting.svclog
docsraw/tools/FSharp.Formatting.svclog
4 changes: 2 additions & 2 deletions FSharp.ProjectScaffold.sln
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tools", "tools", "{83F16175
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "content", "content", "{8E6D5255-776D-4B61-85F9-73C37AA1FB9A}"
ProjectSection(SolutionItems) = preProject
docs\content\index.fsx = docs\content\index.fsx
docs\content\tutorial.fsx = docs\content\tutorial.fsx
docsraw\content\index.fsx = docsraw\content\index.fsx
docsraw\content\tutorial.fsx = docsraw\content\tutorial.fsx
EndProjectSection
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{ED8079DD-2B06-4030-9F0F-DC548F98E1C4}"
Expand Down
51 changes: 18 additions & 33 deletions build.template
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ open System.Diagnostics
// - for version and project name in generated AssemblyInfo file
// - by the generated NuGet package
// - to run tests and to publish documentation on GitHub gh-pages
// - for documentation, you also need to edit info in "docs/tools/generate.fsx"
// - for documentation, you also need to edit info in "docsraw/tools/generate.fsx"

// The name of the project
// (used by attributes in AssemblyInfo, name of a NuGet package and directory in 'src')
Expand Down Expand Up @@ -128,7 +128,7 @@ let vsProjProps =

Target "Clean" (fun _ ->
!! solutionFile |> MSBuildReleaseExt "" vsProjProps "Clean" |> ignore
CleanDirs ["bin"; "temp"; "docs/output"]
CleanDirs ["bin"; "temp"; "docs"]
)

// --------------------------------------------------------------------------------------
Expand Down Expand Up @@ -201,7 +201,7 @@ let executeFAKEWithOutput workingDirectory script fsiargs envArgs =
// Documentation
let buildDocumentationTarget fsiargs target =
trace (sprintf "Building documentation (%s), this could take some time, please wait..." target)
let exit = executeFAKEWithOutput "docs/tools" "generate.fsx" fsiargs ["target", target]
let exit = executeFAKEWithOutput "docsraw/tools" "generate.fsx" fsiargs ["target", target]
if exit <> 0 then
failwith "generating reference documentation failed"
()
Expand All @@ -225,31 +225,31 @@ let generateHelp fail =
generateHelp' fail false

Target "GenerateHelp" (fun _ ->
DeleteFile "docs/content/release-notes.md"
CopyFile "docs/content/" "RELEASE_NOTES.md"
Rename "docs/content/release-notes.md" "docs/content/RELEASE_NOTES.md"
DeleteFile "docsraw/content/release-notes.md"
CopyFile "docsraw/content/" "RELEASE_NOTES.md"
Rename "docsraw/content/release-notes.md" "docsraw/content/RELEASE_NOTES.md"

DeleteFile "docs/content/license.md"
CopyFile "docs/content/" "LICENSE.txt"
Rename "docs/content/license.md" "docs/content/LICENSE.txt"
DeleteFile "docsraw/content/license.md"
CopyFile "docsraw/content/" "LICENSE.txt"
Rename "docsraw/content/license.md" "docsraw/content/LICENSE.txt"

generateHelp true
)

Target "GenerateHelpDebug" (fun _ ->
DeleteFile "docs/content/release-notes.md"
CopyFile "docs/content/" "RELEASE_NOTES.md"
Rename "docs/content/release-notes.md" "docs/content/RELEASE_NOTES.md"
DeleteFile "docsraw/content/release-notes.md"
CopyFile "docsraw/content/" "RELEASE_NOTES.md"
Rename "docsraw/content/release-notes.md" "docsraw/content/RELEASE_NOTES.md"

DeleteFile "docs/content/license.md"
CopyFile "docs/content/" "LICENSE.txt"
Rename "docs/content/license.md" "docs/content/LICENSE.txt"
DeleteFile "docsraw/content/license.md"
CopyFile "docsraw/content/" "LICENSE.txt"
Rename "docsraw/content/license.md" "docsraw/content/LICENSE.txt"

generateHelp' true true
)

Target "KeepRunning" (fun _ ->
use watcher = !! "docs/content/**/*.*" |> WatchChanges (fun changes ->
use watcher = !! "docsraw/content/**/*.*" |> WatchChanges (fun changes ->
generateHelp' true true
)

Expand All @@ -273,7 +273,7 @@ F# Project Scaffold ({0})
=========================
*)
"""
let targetDir = "docs/content" </> lang
let targetDir = "docsraw/content" </> lang
let targetFile = targetDir </> "index.fsx"
ensureDirectory targetDir
System.IO.File.WriteAllText(targetFile, System.String.Format(content, lang))
Expand All @@ -289,7 +289,7 @@ Target "AddLangDocs" (fun _ ->
failwithf "Language must be 2 or 3 characters (ex. 'de', 'fr', 'ja', 'gsw', etc.): %s" lang

let templateFileName = "template.cshtml"
let templateDir = "docs/tools/templates"
let templateDir = "docsraw/tools/templates"
let langTemplateDir = templateDir </> lang
let langTemplateFileName = langTemplateDir </> templateFileName

Expand All @@ -305,17 +305,6 @@ Target "AddLangDocs" (fun _ ->
// --------------------------------------------------------------------------------------
// Release Scripts

Target "ReleaseDocs" (fun _ ->
let tempDocsDir = "temp/gh-pages"
CleanDir tempDocsDir
Repository.cloneSingleBranch "" (gitHome + "/" + gitName + ".git") "gh-pages" tempDocsDir

CopyRecursive "docs/output" tempDocsDir true |> tracefn "%A"
StageAll tempDocsDir
Git.Commit.Commit tempDocsDir (sprintf "Update generated documentation for version %s" release.NugetVersion)
Branches.push tempDocsDir
)

#load "paket-files/build/fsharp/FAKE/modules/Octokit/Octokit.fsx"
open Octokit

Expand Down Expand Up @@ -365,7 +354,6 @@ Target "All" DoNothing
==> "NuGet"
==> "BuildPackage"
==> "All"
=?> ("ReleaseDocs",isLocalBuild)

"GenerateHelp"
==> "GenerateReferenceDocs"
Expand All @@ -381,7 +369,4 @@ Target "All" DoNothing
==> "PublishNuget"
==> "Release"

"ReleaseDocs"
==> "Release"

RunTargetOrDefault "All"
17 changes: 0 additions & 17 deletions docs/output/README.md
View file

This file was deleted.

0 docs/content/index.fsx → docsraw/content/index.fsx
View file
File renamed without changes.
0 docs/content/tutorial.fsx → docsraw/content/tutorial.fsx
View file
File renamed without changes.
0 docs/files/img/logo-template.pdn → docsraw/files/img/logo-template.pdn
View file
File renamed without changes.
0 docs/files/img/logo.png → docsraw/files/img/logo.png
View file
File renamed without changes
8 changes: 4 additions & 4 deletions docs/tools/generate.template → docsraw/tools/generate.template
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// --------------------------------------------------------------------------------------
// Builds the documentation from `.fsx` and `.md` files in the 'docs/content' directory
// (the generated documentation is stored in the 'docs/output' directory)
// Builds the documentation from `.fsx` and `.md` files in the 'docsraw/content' directory
// (the generated documentation is stored in the 'docsraw/output' directory)
// --------------------------------------------------------------------------------------

// Binaries that have XML documentation (in a corresponding generated XML file)
Expand Down Expand Up @@ -41,13 +41,13 @@ open FSharp.MetadataFormat
#if RELEASE
let root = website
#else
let root = "file://" + (__SOURCE_DIRECTORY__ @@ "../output")
let root = "file://" + (__SOURCE_DIRECTORY__ @@ "../../docs")
#endif

// Paths with template/source/output locations
let bin = __SOURCE_DIRECTORY__ @@ "../../bin"
let content = __SOURCE_DIRECTORY__ @@ "../content"
let output = __SOURCE_DIRECTORY__ @@ "../output"
let output = __SOURCE_DIRECTORY__ @@ "../../docs"
let files = __SOURCE_DIRECTORY__ @@ "../files"
let templates = __SOURCE_DIRECTORY__ @@ "templates"
let formatting = __SOURCE_DIRECTORY__ @@ "../../packages/build/FSharp.Formatting/"
Expand Down
0 docs/tools/templates/template.cshtml → docsraw/tools/templates/template.cshtml
View file
File renamed without changes.
2 changes: 1 addition & 1 deletion init.fsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -235,7 +235,7 @@ let generate templatePath generatedFilePath =
print (sprintf "# Generated %s" generatedFilePath)

generate (localFile "build.template") (localFile "build.fsx")
generate (localFile "docs/tools/generate.template") (localFile "docs/tools/generate.fsx")
generate (localFile "docsraw/tools/generate.template") (localFile "docsraw/tools/generate.fsx")

//Handle source control
let isGitRepo () =
Expand Down

7 comments on commit 265feb0

@gusty
Copy link
Member

@gusty gusty commented on 265feb0 Oct 21, 2017

Choose a reason for hiding this comment

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

@jackfoxy Why did you remove the target ReleaseDocs?

I can't find any good reason in the commit message and this was the target I used the most.

@jackfoxy
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@gusty don't remember exactly, but probably because it is no longer needed. This PR, and a later one that renames docsraw folder to docsrc, changes the scaffold infrastructure to allow the more recent and simpler method of publishing docs on GitHub by simply enabling github.io to publish the "docs" folder in the master branch. No more hassling with a git orphan branch named gh-pages.

@forki
Copy link
Member

@forki forki commented on 265feb0 Oct 21, 2017 via email

Choose a reason for hiding this comment

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

@gusty
Copy link
Member

@gusty gusty commented on 265feb0 Oct 21, 2017

Choose a reason for hiding this comment

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

Thanks @jackfoxy at the same time you replied I found the issue #304 and it seems I'm not the only one who miss this.

But can you tell me what's the process to Release only the docs with a single command now?

@jackfoxy
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@gusty Docs get released with the master branch. I'm not opposed to rolling back ProjectScaffold. Or reimplementing ReleaseDocs in a new PR can't be that hard. I just thought, and still do think, the gh-pages way of maintaining docs is complicated for people not too familiar with git.

I only have my own experience to go on. Everyone develops their own workflow. I still think (but have no evidence) most new adopters would rather not deal with gh-pages. Do they really want their published docs to not correspond to the master branch? Again, PR to put ReleaseDocs back in and both methods work.

Anyway, I also think the future of ProjectScaffold is for people to maintain their own forks. I maintain my own fork. Publishing a directory of interesting forks might be a good idea.

@forki
Copy link
Member

@forki forki commented on 265feb0 Oct 22, 2017 via email

Choose a reason for hiding this comment

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

@gusty
Copy link
Member

@gusty gusty commented on 265feb0 Oct 22, 2017

Choose a reason for hiding this comment

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

Docs get released with the master branch.

So there's no way to release the docs with a single command, as it was before.

still do think, the gh-pages way of maintaining docs is complicated for people not too familiar with git.

I agree, it is complicated to set up, but once done it's quite easy to update. This can be solved with a very detailed guide on how to set up gh-pages step by step.

Apart from that I agree with @forki in that docs are like the .exe or the .dll that is produced by the source files, so it shouldn't go into the source code.

Publishing a directory of interesting forks might be a good idea.

Not sure. Let's think about independent features: Feature A, Feature B and Feature C where one of these features is the docs. Now if we start forking we'll have Feature A' with B and C, or B' with A and C, but then someone prefers A' with B' but with C and so on. We'll need to have many combinations and that's hard to maintain.

So I think if we want to have different features, we should implement them all and ask the user when setting up his project which one he prefers.

Please sign in to comment.