search

dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.09k stars 868 forks source link

Edit on Github Link Missing #677

Closed sahammer closed 8 years ago

sahammer commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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

hellosnow commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

@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": "© 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 commented 8 years ago
image image
drizzlelabs commented 8 years ago

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

hellosnow commented 8 years ago

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 commented 8 years ago 
<!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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago
capture
drizzlelabs commented 8 years ago

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 commented 8 years ago

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

drizzlelabs commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

That would actually work well I think!

sahammer commented 8 years ago

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 commented 8 years ago

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

sahammer commented 8 years ago

Awesome thanks @superyyrrzz we will check it out

drizzlelabs commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

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 commented 5 years ago

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