Edit on Github Link Missing #677

sahammer · 2016-09-06T22:01:27Z

Hello,

We've created a couple of basic documentation pages on an internal repo which we have been successfully generating documentation from.

However - we've tried a variety of methods and the "Improve this Doc" link is not appearing in any of our documentation. We have an existing .git folder in the repo root that contains the appropriate information but have been unable to determine why the link is not appearing.

We have also added in the gitContribute metadata as well to see if that would make it appear and it has not.

Any suggestions as to what we may be missing?

superyyrrzz · 2016-09-07T02:20:26Z

Not sure whether it's caused by this... Recently we have some UX change, which moved this button to the side affix in the right of page. Do you miss it as it less apparent than before?

sahammer · 2016-09-07T02:52:56Z

Unfortunately the link is not appearing anywhere. At a loss for what to look at next.

hellosnow · 2016-09-07T02:54:20Z

@sahammer we moved the "Improve this doc" to right side affix panel. Sample page is here: http://dotnet.github.io/docfx/tutorial/docfx_getting_started.html, if you cannot find it, did you set "_disableContribution" in docfx.json? The value of "_disableContribution" should be "false" there.

hellosnow · 2016-09-07T02:56:48Z

And also, the "_disableAffix" should be "false" to enable affix on right hand side, could you share your docfx.json with us if possible?

drizzlelabs · 2016-09-07T03:01:39Z

@hellosnow

Here is the contents:

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "*.csproj"
          ],
          "cwd": ".",
          "exclude": [
            "**/obj/**",
            "**/bin/**",
            "docs/**"
          ]
        }
      ],
      "dest": "obj/api"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml"
        ],
        "cwd": "obj"
      },
      {
        "files": [
          "api/*.md",
          "articles/**.md",
          "toc.yml",
          "*.md"
        ],
        "exclude": [
          "obj/**",
          "docs/**"
        ]
      }
    ],
    "dest": "docs",
    "globalMetadata": {
      "_appTitle": "DocFX website",
      "_appFooter": "&#0169; 2016 Graviton",
      "_enableSearch": "true",
      "_disableContribution": "false",
      "_disableAffix":  "false"
    },
    "overwrite": [
      {
        "files": [
          "apidoc/**.md"
        ],
        "exclude": [
          "obj/**",
          "docs/**"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ],
        "exclude": [
          "obj/**",
          "docs/**"
        ]
      }
    ],
    "template": [
      "default",
      "graviton_template"
    ]
  }
}

drizzlelabs · 2016-09-07T03:03:44Z

drizzlelabs · 2016-09-07T03:04:40Z

We've tried going straight from source, dnx, and Visual Studio. All the same results with version 2.4.

hellosnow · 2016-09-07T03:13:06Z

The docfx.json looks good. For better investigation, is is possible to share the html file content which could not show "Improve this doc" to us?

drizzlelabs · 2016-09-07T03:19:57Z

<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>

  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Add your introductions here! | DocFX website </title>
    <meta name="viewport" content="width=device-width">
    <meta name="title" content="Add your introductions here! | DocFX website ">
    <meta name="generator" content="docfx 2.4.0.0">

    <link rel="shortcut icon" href="../favicon.ico">
    <link rel="stylesheet" href="../styles/docfx.vendor.css">
    <link rel="stylesheet" href="../styles/docfx.css">
    <link rel="stylesheet" href="../styles/main.css">
    <meta property="docfx:navrel" content="../toc.html">
    <meta property="docfx:tocrel" content="toc.html">
    <meta property="docfx:rel" content="../">
  </head>
  <body data-spy="scroll" data-target="#affix">
    <div id="wrapper">
      <header>

        <nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
          <div class="container">
            <div class="navbar-header">
              <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
                <span class="sr-only">Toggle navigation</span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
              </button>
              <a class="navbar-brand" href="../index.html">
                <img id="logo" class="svg" src="../logo.svg" alt="">
              </a>
            </div>
            <div class="collapse navbar-collapse" id="navbar">
              <form class="navbar-form navbar-right" role="search" id="search">
                <div class="form-group">
                  <input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
                </div>
              </form>
            </div>
          </div>
        </nav>

        <div class="subnav navbar navbar-default">
          <div class="container hide-when-search" id="breadcrumb">
            <ul class="breadcrumb">
              <li></li>
            </ul>
          </div>
        </div>
      </header>
      <div class="container body-content">

        <div id="search-results">
          <div class="search-list"></div>
          <div class="sr-items"></div>
          <ul id="pagination"></ul>
        </div>
      </div>
      <div role="main" class="container body-content hide-when-search">

        <div class="sidenav hide-when-search">
          <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
          <div class="sidetoggle collapse" id="sidetoggle">
            <div id="sidetoc"></div>
          </div>
        </div>
        <div class="article row grid-right">
          <div class="col-md-12">
            <article class="content wrap" id="_content" data-uid="">
              <h1 id="add-your-introductions-here">Add your introductions here!</h1>


            </article>
          </div>
        </div>
      </div>

      <footer>
        <div class="grad-bottom"></div>
        <div class="footer">
          <div class="container">
            <span class="pull-right">
              <a href="#top">Back to top</a>
            </span>
            &#0169; 2016 Graviton

          </div>
        </div>
      </footer>
    </div>

    <script type="text/javascript" src="../styles/docfx.vendor.js"></script>
    <script type="text/javascript" src="../styles/docfx.js"></script>
    <script type="text/javascript" src="../styles/main.js"></script>
    <script>hljs.initHighlightingOnLoad();</script>
  </body>
</html>

Thanks again!

hellosnow · 2016-09-07T03:45:09Z

I found "class="col-md-12"" from your html page, and according to our template conceptual.html.primary.tmpl, looks like the "_disableAffix" is set to "true"? But it's obviously not from your docfx.json.

{{#_disableAffix}}
     <div class="col-md-12">
{{/_disableAffix}}

Let's confirm something:
If you open the same html page in browser, "In this article" also not show on the right hand side, correct?

And more, could you try to generate the html pages using our test project https://github.com/docascode/docfx-seed to check whether it contains "Improve this doc"?

drizzlelabs · 2016-09-07T03:56:59Z

I went and viewed the same html page in browser, and it does not show on the right hand side still. I went ahead and generated the seed docs and the "Improve this doc" is still not present. I do see the right article section system though. I'm still using build 2.4. I also tested again with using the docfx.json file posted above and built it again, still no success. Finally I applied the "graviton_template" and that section disappeared. I used the export template option to adjust a few css colors. I won't use that template for testing purposes.

hellosnow · 2016-09-07T06:22:42Z

Did you generate the docfx-seed using pure docfx 2.4 version(without any additional changes)? I downloaded docfx Version 2.4, build and serve docfx-seed, "Improve this doc" appears on right hand side.

In fact, the keypoint is not whether showing "Improve this doc", but showing affix including "Improve this doc", "In this article" and bookmarks.

drizzlelabs · 2016-09-07T11:41:14Z

@hellosnow On a different machine, I went and downloaded the docfx.zip file and the docfx-seed master branch as a zip file. From there I ran:

PS C:\users\useraccount\Downloads\docfx> .\docfx.exe 'C:\users\useraccount\Downloads\docfx-seed-master\docfx-seed-master\docfx.json'

... and served the page up. The results are as follows in Microsoft Edge and Firefox:

drizzlelabs · 2016-09-07T11:43:26Z

drizzlelabs · 2016-09-07T12:20:49Z

When I proceed to clone the git repo in a folder on my machine, I'm now able to see the "Improve this doc" link. I'm going to try this again with the template after I make it to work.

Thanks again for you help!

hellosnow · 2016-09-07T14:09:47Z

sure @drizzlelabs , let's sync after you retry.

drizzlelabs · 2016-09-07T14:38:53Z

@hellosnow I think we narrowed down the issue to Github Enterprise. Looking through the code, is it looking for the repo link out matching github.com?

drizzlelabs · 2016-09-07T14:51:15Z

I just confirmed that is our issue. I went into the .git\config file and modified our repo to a random github.com location and it worked.

'''
[core]
repositoryformatversion = 0
filemode = false
bare = false
logallrefupdates = true
symlinks = false
ignorecase = true
[remote "origin"]
url = https://github.com/repotesting/docfx-seed.git
fetch = +refs/heads/:refs/remotes/origin/
[branch "master"]
remote = origin
merge = refs/heads/master
[remote "docascode"]
url = https://github.com/docascode/docfx-seed.git
[remote "docascode"]
fetch = +refs/heads/:refs/remotes/docascode/
'''

sahammer · 2016-09-07T14:57:53Z

In reviewing the source it does appear that there are a few places where there are some regex checks for github.com meaning the link will never show on Enterprise GitHub deployments. In reviewing past issues on this repo I don't see where anyone else has reported this.

Is there another way to check the config vs matching it with a URL? It appears it contains several other configuration items.

drizzlelabs · 2016-09-07T16:24:03Z

I tried to override the git repo location using:

"_gitContribute": {
        "repo": "https://github.contoso.com/Engineering/Documentation.git",
        "branch": "master",
        "path": ""
      }

... it didn't work. When I changed it to:

"_gitContribute": {
        "repo": "https://github.com/Engineering/Documentation.git",
        "branch": "master",
        "path": ""
      }

... it worked.

superyyrrzz · 2016-09-08T01:40:43Z

@sahammer You're right. As different git hosting service has different form of URL, we first test the domain name, then we can know the right way to generate URL, for github.com or visualstudio.com.
Does your Enterprise GitHub has the same form of URL as github.com? If so, we can find a way to skip the check and force generating GitHub like URL.

sahammer · 2016-09-08T01:47:47Z

@superyyrrzz In our case it's github.ourcompany.com, but as far as we have observed the path is exactly the same as github generates, the same content is there. So along the lines of github.ourcompany.com/ourteam/ourrepo/...

Ultimately you could have any domain name, but the actual path is the same. It would be nice if the override you can put in for the branch could also override the full URL.

ie:

"_gitContribute": {
        "repo": "https://github.contoso.com/Engineering/Documentation.git",
        "branch": "master",
        "path": ""
      }

Would make it go to that full repo path, rather than just the branch. Any time we change the repo path the improve this document link disappears. Obviously if someone puts in something invalid, the link would not work which of course is a downside.

superyyrrzz · 2016-09-08T02:16:00Z

Yes the full URL should be overwritten. What about providing a switch like _generateGithubAlikeUrl? If you set this, we can skip the check of domain name, then generate a URL like github.ourcompany.com/ourteam/ourrepo/file....

sahammer · 2016-09-08T02:26:03Z

That would actually work well I think!

sahammer · 2016-09-09T21:58:17Z

We were able to temporarily modify the source for the functionality we wanted. Once _generateGithubAlikeUrl is added we will update to the latest version.

Thanks again!

superyyrrzz · 2016-09-14T09:47:43Z

It's implemented in dev branch. You can try this or wait for the latest version by adding "_gitUrlPattern": "github" in global metadata.

sahammer · 2016-09-14T13:36:42Z

Awesome thanks @superyyrrzz we will check it out

drizzlelabs · 2016-09-14T16:14:24Z

@superyyrrzz Thanks a ton! I was able to build docfx from the dev branch and it works perfectly with that line. I tried multiple url's and all seem to work as long as they follow the traditional git format.

sahammer · 2016-09-15T21:58:41Z

@superyyrrzz Quick question (I can open another issue if required)

Is it possible to show who has contributed to an article? We noticed this was a thing on the Microsoft Azure documentation (Which we assume uses docfx :)

Example:
https://azure.microsoft.com/en-us/documentation/articles/site-recovery-deploy-with-powershell/

superyyrrzz · 2016-09-18T05:29:27Z

I'm afraid not for now. It's generated by a module in another system, and some work is needed make it a built-in feature of docfx.

Konard · 2019-08-13T10:30:15Z

For me these two settings worked:

      "_gitContribute": {
        "branch": "master"
      },
      "_gitUrlPattern": "github"

"_gitUrlPattern": "github" alone was not enough.
https://github.com/linksplatform/Threading/blob/a7a64f2adb2a8db16a5624a0a59d37d54e5b9791/docfx.json#L28

hellosnow self-assigned this Sep 7, 2016

chenkennt assigned superyyrrzz and unassigned hellosnow Sep 9, 2016

superyyrrzz mentioned this issue Sep 13, 2016

support choose gitUrlPattern #696

Merged

superyyrrzz closed this as completed Oct 21, 2016

superyyrrzz mentioned this issue Jan 11, 2017

"Improve this Document" link not appearing for Gitlabs. #1144

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Edit on Github Link Missing #677

Edit on Github Link Missing #677

sahammer commented Sep 6, 2016

superyyrrzz commented Sep 7, 2016

sahammer commented Sep 7, 2016

hellosnow commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016 •

edited

Loading

drizzlelabs commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

sahammer commented Sep 7, 2016 •

edited

Loading

drizzlelabs commented Sep 7, 2016 •

edited

Loading

superyyrrzz commented Sep 8, 2016

sahammer commented Sep 8, 2016 •

edited

Loading

superyyrrzz commented Sep 8, 2016

sahammer commented Sep 8, 2016

sahammer commented Sep 9, 2016

superyyrrzz commented Sep 14, 2016

sahammer commented Sep 14, 2016

drizzlelabs commented Sep 14, 2016

sahammer commented Sep 15, 2016

superyyrrzz commented Sep 18, 2016

Konard commented Aug 13, 2019

Edit on Github Link Missing #677

Edit on Github Link Missing #677

Comments

sahammer commented Sep 6, 2016

superyyrrzz commented Sep 7, 2016

sahammer commented Sep 7, 2016

hellosnow commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016 • edited Loading

drizzlelabs commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

hellosnow commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

drizzlelabs commented Sep 7, 2016

sahammer commented Sep 7, 2016 • edited Loading

drizzlelabs commented Sep 7, 2016 • edited Loading

superyyrrzz commented Sep 8, 2016

sahammer commented Sep 8, 2016 • edited Loading

superyyrrzz commented Sep 8, 2016

sahammer commented Sep 8, 2016

sahammer commented Sep 9, 2016

superyyrrzz commented Sep 14, 2016

sahammer commented Sep 14, 2016

drizzlelabs commented Sep 14, 2016

sahammer commented Sep 15, 2016

superyyrrzz commented Sep 18, 2016

Konard commented Aug 13, 2019

drizzlelabs commented Sep 7, 2016 •

edited

Loading

sahammer commented Sep 7, 2016 •

edited

Loading

drizzlelabs commented Sep 7, 2016 •

edited

Loading

sahammer commented Sep 8, 2016 •

edited

Loading