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.

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
Closed

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

pvandervelde opened this issue Jul 8, 2016 · 9 comments
Assignees
Milestone

Comments

@pvandervelde
Copy link

@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
Copy link
Contributor

@superyyrrzz superyyrrzz commented Jul 8, 2016

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

    "globalMetadata": {
      "newFileRepository": {
        "branch": "yourBranch"
      }
    },
@pvandervelde
Copy link
Author

@pvandervelde 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
Copy link
Contributor

@superyyrrzz 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
Copy link
Author

@pvandervelde pvandervelde commented Jul 9, 2016

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

@superyyrrzz
Copy link
Contributor

@superyyrrzz 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
Copy link
Contributor

@superyyrrzz 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
Copy link
Author

@pvandervelde pvandervelde commented Jul 22, 2016

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

@guardrex
Copy link

@guardrex 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
Copy link
Contributor

@superyyrrzz 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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.