I'm writing some docs for Sphinx/rst. How can I link to something on local disk which is relative to the page you're viewing?
For example:
====================
My App documentation
====================
The official My App documentation can be found here:
https://myapp.com/docs
A local mirror is available:
../../_static/docs_mirror/index.html
On my machine, the _static folder resides in:
file:///Users/fredrik/code/repos/myapp/docs/_static
...but I don't want to hard-code that path, as that path might not be the same path for another user who has downloaded cloned the repository.
Here is one way to do it:
`local mirror <_static/docs_mirror/index.html>`_
Another option:
`local mirror`_
.. _local mirror: _static/docs_mirror/index.html
Reference: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#hyperlink-references.
Related
I want to change my site using Hugo. I get stuck with modules. As per documentation (e.g. this theme) I just add theme = "github.com/nodejh/hugo-theme-mini" to the config file. It fails like this:
WARN ... found no layout file for "HTML" for kind "term": You should ...
if I perform hugo mod vendor the directory structure of the theme seems created in the _vendor dir, but there is not a single file inside. which explains the "not found" error in my eyes.
nothing (!) is rendered.
I also have this effect with a couple of other themes (I thinknoteworthy being one of them).
Set up a clean project
hugo new site testModules
cd testModules
and enable Hugo modules
hugo mod init randomName`
Paste the following lines in config.toml:
baseURL = "http://example.org/"
title = "Hugo Modules Test"
[module]
[[module.imports]]
path = "github.com/nodejh/hugo-theme-mini"
Start Hugo
hugo serve -D
Done!
The content of github.com/nodejh/hugo-theme-mini" will be downloaded and used as theme.
See the theme's documentation to add content
Optional:
hugo mod vendor
will make the content of the remote repo available in the _vendor folder.
(Surprisingly the content of exampleSite was not downloaded during the quick test I made)
My module is gitlab.com/getsote/utilities/slogger
My repository is gitlab.com/getsote/utilities/slogger.git
When I run go get gitlab.com/getsote/utilities/slogger, I get the message below.
Scotts-Mac-mini:seeding syacko$ go get gitlab.com/getsote/utilities/slogger
go get gitlab.com/getsote/utilities/slogger: module gitlab.com/getsote/utilities/slogger: git ls-remote -q origin in /Users/syacko/workspace/sotesoft/golang/pkg/mod/cache/vcs/80b3644beae1b986f1c659355360479e2463820660aa328d2edb1e571aba259b: exit status 128:
remote: The project you were looking for could not be found.
fatal: repository 'https://gitlab.com/getsote/utilities.git/' not found
Scotts-Mac-mini:seeding syacko$
The gitlab.com/getsote/utilities.git is a sub-directory and not a repository. I don't understand why go get is going to the utilities as a repository?
==========================
PREVIOUS Updates
Directory Structure:
GOPATH/src/slogger
|----go.mod
|----slogger.go
|----slogger_test.go
go.mod file
module slogger or gitlab.com/getsote/utilities/slogger -> still gets the error below
go 1.14
gitlab.com/getsote/utilities contains repository slogger.git
I have run a test to see if the issue is the number of nodes in the path. So, I create a new repository with no sub-directory and pushed the slogger code. Then ran go get gitlab.com/getsote/slogger which generate a different error message.
GOPATH/gitlab.com/getsote/test-go-mod -> create new directory and added slogger files listed above
gitblab.com/getsote/test-go-mod -> new repository with one less level
Scotts-Mac-mini:test-go-mod syacko$ go get gitlab.com/getsote/test-go-mod
go: downloading gitlab.com/getsote/test-go-mod v0.0.0-20200409023538-794310bf7cf9
go get gitlab.com/getsote/test-go-mod: gitlab.com/getsote/test-go-mod#v0.0.0-20200409023538-794310bf7cf9: verifying module: gitlab.com/getsote/test-go-mod#v0.0.0-20200409023538-794310bf7cf9: reading https://sum.golang.org/lookup/gitlab.com/getsote/test-go-mod#v0.0.0-20200409023538-794310bf7cf9: 410 Gone
server response:
not found: gitlab.com/getsote/test-go-mod#v0.0.0-20200409023538-794310bf7cf9: invalid version: git fetch -f origin refs/heads/*:refs/heads/* refs/tags/*:refs/tags/* in /tmp/gopath/pkg/mod/cache/vcs/7753c92c9bd1419156d8120684b7f3707fd207e01a2947ba89e2acfd2ecfb4d0: exit status 128:
fatal: could not read Username for 'https://gitlab.com': terminal prompts disabled
Scotts-Mac-mini:test-go-mod syacko$
This is still getting the status error of 128 for the missing version. Additionally, it is looking in the right location for the code. If this is true, then I just need help with the version missing. Moving to a shorted directory structure is doable.
========================
Newest Update
#praveent > The solution at https://medium.com/cloud-native-the-gathering/go-modules-with-private-git-repositories-dfe795068db4 didn't work for me. So I started from scratch to see how to resolve the issue.
The reason is because for a git repository it assumes that utilities is the repo and not utilities/slogger
There is a way to override this behavior by implementing go get API. But, gitlab is yet to implement the same due to security concerns. You can read more here. Gitlab issue
Update: Add reference to gitlab issue tracking this problem.
So, here is how I got this to work using gitlab.com. I'm not saying other ways will not work, they just didn't for me and my setup. First, since I don't care if the code is available to the public, I created a new group at gitlab.com. This new group is public from the start, so no need to adjust permissions. Then I create a repository called packages and cloned the repository to my local machine with the same directory structure that is in gitlab.com, gitlab.com/soteapps/packages with ~/workspace/soteapps/packages on my machine. Both of these are out side the GOPATH. I'm not sure this matters, but it is working this way, so I'm putting it here.
Under packages, I copied the slogger directory and code.
cp -R slogger ~/workspace/soteapps/packages/.
Edited the go.mod file to match the repository structure, which is in the packages directory. There is no go.mod file in the slogger directory.
module gitlab.com/soteapps/packages
go 1.14
Edited the hello.go import to match the package.
package main
import (
"fmt"
"rsc.io/quote"
"gitlab.com/soteapps/packages/slogger"
)
func main() {
fmt.Println(quote.Hello())
slogger.Info("Test message")
}
Built the program using go build -o hello and then ran it hello with the following results:
Scotts-Mac-mini:hello syacko$ hello
Hello, world.
INFO:2020/04/10 21:11:33 Test message
Scotts-Mac-mini:hello syacko$
Worked! Thank you all that helped. This wouldn't of gotten solved without your help.
Note: This only works for public repositories.
I was trying to serve a specific local go file as a documentation web page, but was not able to do it.
The official godoc documentation says:
With the -http flag (i.e. the godoc command), it runs as a web server and presents the documentation as a web page.
user_me$ godoc -http=:6060
This does create something similar as the go page but it does not render the specific file that I want to render. So I tried to provide the name of the file I wanted:
user_me$ godoc -http=:6000 hello.go
However, it just replies with:
usage: godoc package [name ...]
godoc -http=:6060
-ex=false: show examples in command line mode
-goroot="/usr/local/go": Go root directory
-html=false: print HTML in command-line mode
-http="": HTTP service address (e.g., ':6060')
-httptest.serve="": if non-empty, httptest.NewServer serves on this address and blocks
-index=false: enable search index
-index_files="": glob pattern specifying index files;if not empty, the index is read from these files in sorted order
-index_throttle=0.75: index throttle value; 0.0 = no time allocated, 1.0 = full throttle
-links=true: link identifiers to their declarations
-maxresults=10000: maximum number of full text search results shown
-notes="BUG": regular expression matching note markers to show
-play=false: enable playground in web interface
-q=false: arguments are considered search queries
-server="": webserver address for command line searches
-src=false: print (exported) source in command-line mode
-tabwidth=4: tab width
-templates="": directory containing alternate template files
-timestamps=false: show timestamps with directory listings
-url="": print HTML for named URL
-v=false: verbose mode
-write_index=false: write index to a file; the file name must be specified with -index_files
-zip="": zip file providing the file system to serve; disabled if empty
I also tried:
user_me$ godoc -url="localhost:8080" hello.go
but it didn't work.
I also tried:
godoc -server=localhost:8080 hello.go
but it replied with:
2014/07/01 10:45:56 open /usr/local/go/src/pkg/hello.go: no such file or directory
I even tried just generating the html thing itself:
godoc -html hello.go > hello.html
same error as above.
I also tried (since it was complaining that there was no file in the pkg dir):
godoc -html -goroo=$GOPATH hello.go > hello.html
At the end, I gave up. I don't know how this godoc thing works. I installed the hello.go program so that I there was something in the pkg file in the workspace. How do you generate a webpage with your documentation for your code?
godoc operates on package and type names, not filenames.
For example, to learn about io/ioutil package:
text output: godoc io/ioutil
just the ReadAll function: godoc io/ioutil ReadAll
in HTML: godoc -html io/ioutil ReadAll
in the browser:
godoc -http=:6060
click Packages and navigate from there
or go directly to http://localhost:6060/pkg/io/ioutil#ReadAll
To view documentation for your own code, it has to be included in your GOPATH.
Suppose your GOPATH includes $HOME/go/src, and the file you are interested in is $HOME/go/src/hey/world/doc.go, you would run:
godoc hey/world
...or start godoc in HTTP mode and browse to http://localhost:6060/pkg/hey/world
By default, godoc looks at the packages it finds via $GOROOT and $GOPATH. So given that your package is in Go workspace i.e in GOPATH, you can run
godoc fmt
which prints out documentation for fmt package.
If you want to generate docs for your package foo which is in $GOPATH/src/github.com/abcd/foo location, you should run
godoc github.com/abcd/foo
With the -http flag, godoc runs as a web server and presents the documentation as a web page.
godoc -http=:6060
Now navigate to http://localhost:6060/pkg/github.com/abcd/foo in browser to find docs as web page.
The -play flag can be used to enable playground in web interface.
To show HTML doc generated for your own code
Step 1) At command line start up the document web server, that is:
C:\>godoc -http=:6060
Step 2) Open a browser and use an explicit url the folder your code is.
The URL structure comes from the folder names under your GOPATH.
For example:
If my GOPATH is c:\go and I have code in c:\go\src\myfolder\mysubfolder
The URL I would uses is http://localhost:6060/pkg/myfolder/mysubfolder and this would show an HTML page for the .go files in there
Also you can use URL http://localhost:6060/pkg/myfolder, which will have a link to mysubfolder
Notes:
I'm not sure how to see your local code at the the http://localhost:6060/pkg level, maybe you can't
It is possible to "specify additional paths" so I don't think it has to be the src folder, see https://blog.golang.org/godoc-documenting-go-code
Running godoc on its own worked for me, but was really slow because it
generates docs for every single package in the standard library, while I only
care about the local package that I am working on. To that end, if your package is in a folder called something, you can move
the folder so that it looks like this:
godoc/src/something
Then, go to the godoc folder, and run
godoc -goroot .
Then, browse to localhost:6060.
On linux, and assuming you have cd'd into the package of which you want to read the documentation.
if you are using go modules, you can run below command
godoc -http=:6060 & xdg-open http://localhost:6060/pkg/$(go list -m)
It uses the -m flag to get the package path even though the root module directory does not contain any .go file.
If you are not yet using modules, you can run,
godoc -http=:6060 & xdg-open http://localhost:6060/pkg/$(go list -f "{{.ImportPath}}")
Note that unlike -m this command will not work appropriately if there is no .go files into the directory.
Check the go list subcommand help at https://golang.org/pkg/cmd/go/internal/list/
I want to create a link that refers to a section defined in another file.
I have found a similar question on "Python-Sphinx: Link to Section in external File" and I noticed there is an extension called "intersphinx".
So I tried this extension, but it doesn't work (Probably my usage is wrong).
I have tried the following.
conf.py
extensions = ['sphinx.ext.todo', 'sphinx.ext.intersphinx']
...
intersphinx_mapping = {'myproject': ('../build/html', None)}
foo.rst
...
****************
Install Bar
****************
Please refer :ref:`Bar Installation Instruction<myproject:bar_installation>`
I want to create a link like 'Bar Installation Instruction' with above markup.
bar.rst
...
**************************
Installation Instruction
**************************
.. _bar_installation:
some text...
When I run make html, I get the following warning and the link is not created.
foo.rst: WARNING: undefined label: myproject:bar_installation (if the link has no caption the label must precede a section header)
Thanks in advance.
Looks like it's not able to find your mapping inventory file. The first part of the tuple serves as the base URL for your links while the second part is the path to the inventory file. I believe the auto downloading of the inventory files (when you pass None) only works with URIs and not file paths.
In this example, I can build the documentation locally, but it will link to http://example.com/docs/bar.html
'myproject': (
'http://example.com/docs/',
'../html/objects.inv'
)
From the official api site it says that core modules are installed at the /lib folder of the root folder of NodeJS, but when I was trying to search for it I didn't see the /lib folder.
Any idea?
Additionally, after I've done a
var a = require("a.js");
is it possible to get the corresponding path to a.js?
that means /lib folder is in source code not your computer. you can see it in repository.
and
there are two patterns for require
absolute path: if the parameter is not started with ./' nor'../', it's absolute path. so node look for it in core module(it's compiled in node runtime) or `node_modules' that you installed locally using npm.
relative path: if the parameter is started with ./ or ../, it's relative path. so node look for it relative path to current position.
it's so simple. and you can use require.resolve('a.js') to get absolute system path. but core modules don't has path since it's built-in.
Although the accepted answer is good enough to resolve the question, it is worth mention that it has some misleading information regarding the patterns of required. From the very Reference Documentation of Node:
A module prefixed with '/' is an absolute path to the file. For example, require('/home/marco/foo.js') will load the file at /home/marco/foo.js.
A module prefixed with './' is relative to the file calling require(). That is, circle.js must be in the same directory as foo.js for require('./circle') to find it.
Without a leading '/' or './' to indicate a file, the module is either a "core module" or is loaded from a node_modules folder.