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

Edit on Github Link Missing #677

Closed
sahammer opened this issue Sep 6, 2016 · 31 comments
Closed

Edit on Github Link Missing #677

sahammer opened this issue Sep 6, 2016 · 31 comments
Assignees

Comments

@sahammer
Copy link

sahammer commented Sep 6, 2016

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

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

sahammer commented Sep 7, 2016

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

@hellosnow
Copy link
Contributor

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

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

drizzlelabs commented Sep 7, 2016

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

image

image

@drizzlelabs
Copy link

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

@hellosnow
Copy link
Contributor

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

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

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

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

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.

@hellosnow hellosnow self-assigned this Sep 7, 2016
@drizzlelabs
Copy link

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

capture

@drizzlelabs
Copy link

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

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

@drizzlelabs
Copy link

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

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

sahammer commented Sep 7, 2016

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

drizzlelabs commented Sep 7, 2016

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

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

sahammer commented Sep 8, 2016

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

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

sahammer commented Sep 8, 2016

That would actually work well I think!

@chenkennt chenkennt assigned superyyrrzz and unassigned hellosnow Sep 9, 2016
@sahammer
Copy link
Author

sahammer commented Sep 9, 2016

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

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

@sahammer
Copy link
Author

Awesome thanks @superyyrrzz we will check it out

@drizzlelabs
Copy link

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

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

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

Konard commented Aug 13, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants