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.

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

Point "Improve this Doc" button to default branch #482

Closed
pvandervelde opened this Issue Jul 8, 2016 · 9 comments

Comments

Projects
None yet
4 participants
@pvandervelde

pvandervelde commented Jul 8, 2016

Is it possible to point the "Improve this Doc" button to a default branch?

I'm using GitFlow for as the workflow for my repository and on top of that builds are never done on master, just on the final commit on the release or hotfix branch. This means that the "Improve this Doc" button in any documentation build that this time also points to the release or hotfix branch. However this branch is only temporary.

So I would like to point the button to the develop branch. Is there a way to do this in the configuration?

@superyyrrzz

This comment has been minimized.

Show comment
Hide comment
@superyyrrzz

superyyrrzz Jul 8, 2016

Collaborator

You can add newFileRepostiry property to globalMetadata in docfx.json:

    "globalMetadata": {
      "newFileRepository": {
        "branch": "yourBranch"
      }
    },
Collaborator

superyyrrzz commented Jul 8, 2016

You can add newFileRepostiry property to globalMetadata in docfx.json:

    "globalMetadata": {
      "newFileRepository": {
        "branch": "yourBranch"
      }
    },
@pvandervelde

This comment has been minimized.

Show comment
Hide comment
@pvandervelde

pvandervelde Jul 9, 2016

So that seems to work in the API documentation part but not in the general documentation part. Both the "Improve this Doc" button in the general documentation and the "View Source" button in the API documentation point to the branch I'm building on. The "Improve this Doc" button in the API documentation points to the branch I specified in the docfx.json file.

My doxfx.json file looks like this:

{
    "metadata": [
        {
            "src": [
                {
                    "cwd": "../../",
                    "exclude": [
                        "**/obj/**",
                        "**/bin/**",
                        "_site/**"
                    ],
                    "files": [
                        "src/**/*.csproj"
                    ]
                }
            ],
            "dest": "obj/api"
        }
    ],
    "build": {
        "content": [
            {
                "files": [
                    "api/**.yml"
                ],
                "cwd": "obj"
            },
            {
                "files": [
                    "api/*.md",
                    "articles/**.md",
                    "toc.yml",
                    "*.md"
                ],
                "exclude": [
                    "obj/**",
                    "_site/**"
                ]
            }
        ],
        "dest": "_site",
        "globalMetadata": {
            "newFileRepository": {
                "branch": "develop"
            },
            "_appFooter": "Copyright (c) - TheNucleus 2013 - 2016. All rights reserved."
        },
        "overwrite": [
            {
                "files": [
                    "apidoc/**.md"
                ],
                "exclude": [
                    "obj/**",
                    "_site/**"
                ]
            }
        ],
        "resource": [
            {
                "files": [
                    "images/**"
                ],
                "exclude": [
                    "obj/**",
                    "_site/**"
                ]
            }
        ],
        "template": [
            "default"
        ]
    }
}

Did I get my configuration incorrect?

pvandervelde commented Jul 9, 2016

So that seems to work in the API documentation part but not in the general documentation part. Both the "Improve this Doc" button in the general documentation and the "View Source" button in the API documentation point to the branch I'm building on. The "Improve this Doc" button in the API documentation points to the branch I specified in the docfx.json file.

My doxfx.json file looks like this:

{
    "metadata": [
        {
            "src": [
                {
                    "cwd": "../../",
                    "exclude": [
                        "**/obj/**",
                        "**/bin/**",
                        "_site/**"
                    ],
                    "files": [
                        "src/**/*.csproj"
                    ]
                }
            ],
            "dest": "obj/api"
        }
    ],
    "build": {
        "content": [
            {
                "files": [
                    "api/**.yml"
                ],
                "cwd": "obj"
            },
            {
                "files": [
                    "api/*.md",
                    "articles/**.md",
                    "toc.yml",
                    "*.md"
                ],
                "exclude": [
                    "obj/**",
                    "_site/**"
                ]
            }
        ],
        "dest": "_site",
        "globalMetadata": {
            "newFileRepository": {
                "branch": "develop"
            },
            "_appFooter": "Copyright (c) - TheNucleus 2013 - 2016. All rights reserved."
        },
        "overwrite": [
            {
                "files": [
                    "apidoc/**.md"
                ],
                "exclude": [
                    "obj/**",
                    "_site/**"
                ]
            }
        ],
        "resource": [
            {
                "files": [
                    "images/**"
                ],
                "exclude": [
                    "obj/**",
                    "_site/**"
                ]
            }
        ],
        "template": [
            "default"
        ]
    }
}

Did I get my configuration incorrect?

@superyyrrzz

This comment has been minimized.

Show comment
Hide comment
@superyyrrzz

superyyrrzz Jul 9, 2016

Collaborator

Got your ideas. Your docfx.json is correct, but currently this can only change the branch name when creating a new file on GitHub. We will investigate this.

Collaborator

superyyrrzz commented Jul 9, 2016

Got your ideas. Your docfx.json is correct, but currently this can only change the branch name when creating a new file on GitHub. We will investigate this.

@pvandervelde

This comment has been minimized.

Show comment
Hide comment
@pvandervelde

pvandervelde Jul 9, 2016

What do you mean with 'creating a new file on GitHub'?

pvandervelde commented Jul 9, 2016

What do you mean with 'creating a new file on GitHub'?

@superyyrrzz

This comment has been minimized.

Show comment
Hide comment
@superyyrrzz

superyyrrzz Jul 9, 2016

Collaborator

"Improve this Doc" links to the conceptual file of the current document. If not found, it will link to a "New File" URL on GitHub.

  • For conceptual documents, as the content in pages are all from conceptual files, so the conceptual file must already exists, which lies in the current branch.
  • For reference documents, as the content is from yml files, mostly the conceptual file doesn't exist. So it leads to the "New File" URL, where newFileRepository takes effects.
Collaborator

superyyrrzz commented Jul 9, 2016

"Improve this Doc" links to the conceptual file of the current document. If not found, it will link to a "New File" URL on GitHub.

  • For conceptual documents, as the content in pages are all from conceptual files, so the conceptual file must already exists, which lies in the current branch.
  • For reference documents, as the content is from yml files, mostly the conceptual file doesn't exist. So it leads to the "New File" URL, where newFileRepository takes effects.
@superyyrrzz

This comment has been minimized.

Show comment
Hide comment
@superyyrrzz

superyyrrzz Jul 22, 2016

Collaborator

@pvandervelde implemented in dev branch. Now you can use the _gitContribute to switch the branch for all the Improve this Doc. Here's an sample:

"globalMetadata": {
      "_gitContribute": {
        "repo": "repoURL",
        "branch": "branchName",
        "path": "overwriteFilePath"
      }
    },

In your case, you need to set "branch": "develop"

Collaborator

superyyrrzz commented Jul 22, 2016

@pvandervelde implemented in dev branch. Now you can use the _gitContribute to switch the branch for all the Improve this Doc. Here's an sample:

"globalMetadata": {
      "_gitContribute": {
        "repo": "repoURL",
        "branch": "branchName",
        "path": "overwriteFilePath"
      }
    },

In your case, you need to set "branch": "develop"

@pvandervelde

This comment has been minimized.

Show comment
Hide comment
@pvandervelde

pvandervelde Jul 22, 2016

Sweet. I'll wait for the next release but that's exactly what I wanted.

pvandervelde commented Jul 22, 2016

Sweet. I'll wait for the next release but that's exactly what I wanted.

@guardrex

This comment has been minimized.

Show comment
Hide comment
@guardrex

guardrex Apr 18, 2018

@superyyrrzz Question on this ...

We have the same problem for the new Blazor docs repo (docs at: http://blazor.net). We're working on master but using the live branch for our live docs. We want the same set up ... "Improve this doc" should open for our readers to edit on the master branch.

I understand everything but one thing ..... What do we need for the overwriteFilePath?

"globalMetadata": {
  "newFileRepository": {
    "branch": "master"
  },
  "_gitContribute": {
    "repo": "https://github.com/aspnet/Blazor.Docs",
    "branch": "master",
    "path": "overwriteFilePath"
  }
}

[EDIT] I found this at https://github.com/dotnet/docfx/blob/2a787812343d8198bb4928213ea120c7f8b00bf5/Documentation/tutorial/docfx.exe_user_manual.md ...

_gitContribute
Customize the Improve this Doc URL button for public contributors. Use repo to specify the contribution repository URL. Use branch to specify the contribution branch. Use apiSpecFolder to specify the folder for new overwrite files. If not set, the git URL and branch of the current git repository will be used.

It looks like you changed path to apiSpecFolder and that we don't need to specify the branch or the apiSpecFolder. Looks like you just need us to do this ...

"globalMetadata": {
  "newFileRepository": {
    "branch": "master"
  },
  "_gitContribute": {
    "branch": "master"
  }
}

guardrex commented Apr 18, 2018

@superyyrrzz Question on this ...

We have the same problem for the new Blazor docs repo (docs at: http://blazor.net). We're working on master but using the live branch for our live docs. We want the same set up ... "Improve this doc" should open for our readers to edit on the master branch.

I understand everything but one thing ..... What do we need for the overwriteFilePath?

"globalMetadata": {
  "newFileRepository": {
    "branch": "master"
  },
  "_gitContribute": {
    "repo": "https://github.com/aspnet/Blazor.Docs",
    "branch": "master",
    "path": "overwriteFilePath"
  }
}

[EDIT] I found this at https://github.com/dotnet/docfx/blob/2a787812343d8198bb4928213ea120c7f8b00bf5/Documentation/tutorial/docfx.exe_user_manual.md ...

_gitContribute
Customize the Improve this Doc URL button for public contributors. Use repo to specify the contribution repository URL. Use branch to specify the contribution branch. Use apiSpecFolder to specify the folder for new overwrite files. If not set, the git URL and branch of the current git repository will be used.

It looks like you changed path to apiSpecFolder and that we don't need to specify the branch or the apiSpecFolder. Looks like you just need us to do this ...

"globalMetadata": {
  "newFileRepository": {
    "branch": "master"
  },
  "_gitContribute": {
    "branch": "master"
  }
}
@superyyrrzz

This comment has been minimized.

Show comment
Hide comment
@superyyrrzz

superyyrrzz Apr 19, 2018

Collaborator

@guardrex overwriteFilePath is for reference page's overwrite document. If someone want to contribute to a class' summary, improve this doc will link to a page to create an overwrite file under overwriteFilePath folder.

Collaborator

superyyrrzz commented Apr 19, 2018

@guardrex overwriteFilePath is for reference page's overwrite document. If someone want to contribute to a class' summary, improve this doc will link to a page to create an overwrite file under overwriteFilePath folder.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment