I want to link to another extra file from my README using Yard.
For example, I have the following line:
...detailed instructions [here](contributing.md) on how to contribute
I want this to link to my file contributing.md in the same directory. I can include the extra file in my .yardopts file, and it will show up in the file list as it should.
So then I found that I can use the yard DSL to make the link work:
...detailed instructions {file:contributing.md here} on how to contribute
However this will not work if the README is being read from Github. Am I naive to want to have it both ways?
Is there a way to link to another .md extra file in markdown using Yard?
I am not sure what you mean with 'if the README is being read from Github'.
The following works for me locally
I add a file to the README via {file:my_file.md test}
I tell yard via the --files command-line option that there is an extra file. The link to 'test' appears in the README. For example in the following way:
bundle exec yard --files my_file.md
Related
I'm trying to stitch together doxygen and sphinx using breathe.
breathe requires you generate doxygen xml output first though: https://breathe.readthedocs.io/en/latest/quickstart.html
I don't want to do this in a separate step. Can I just have sphinx-build execute doxygen for me on build? I just need it to run this command first with some args. Is this possible without having to write a custom sphinx plugin?
EDIT
This works
# Need to sleep because sometimes doxygen doesnt finish writing files before sphinx runs
cwd = os.path.dirname(os.path.realpath(__file__))
os.system('doxygen')
time.sleep(3)
Sure, Sphinx will execute whatever Python code you add to its configuration file conf.py before it starts the documentation build process.
From the Sphinx documentation:
The configuration file is executed as Python code at build time (using importlib.import_module(), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file’s namespace as its configuration.
Which means pre-build tasks can simply be implemented by running the external program, such as Doxygen in your case, as a subprocess anywhere in conf.py.
My first public Python project is now on readthedocs (RTD). There is one problem I'm trying to fix, but without success so far.
I'm using the :async: option to mark coroutines. This is supported by sphinx 2.1+. RTD used sphinx 1.8.5 for my project. All coroutines are simply skipped from the HTML output, i.e not documented at all. That is quite bad.
I created docs/requirements.txt file in my project containing: sphinx>=2.1.0 and in RTD > admin > advanced settings I have entered: /docs/requirements.txt as "A pip requirements file needed to build your documentation. Path from the root of your project.". Don't know if this is the right way to specifiy the sphinx version. Anyway I tried.
The build failed:
ERROR: Could not open requirements file: [Errno 2] No such file or directory: '../../../../../../../../docs/requirements.txt'
How could I overcome these problems to have all coroutines properly documented?
RTD cannot find your requirements file. Try specifying the path relative to the root of your project, not as absolute, by removing the leading slash.
I want to get access to a repository's source code through the git gem. My goal is to go through the source code files and read their content.
From the examples it's unclear to me how I do this? I get the sense that I need to use Git.open, as shown here:
g = Git.open(working_dir, :log => Logger.new(STDOUT))
But it's not clear to me what working_dir is. If I was to target the github.com/ruby-git/ruby-git project there are many ways to reference it. It could be any of these:
git#github.com:ruby-git/ruby-git.git
https://github.com/ruby-git/ruby-git.git
https://github.com/ruby-git/ruby-git
So please let me know if you know how I read the source code files from a repository.
working_dir is directory of your project with Git.
Says your project is in the /home/john_smith_1976/awesome_project folder.
In this case use
require 'git'
g = Git.open('/home/john_smith_1976/awesome_project')
After that for example you can use g.grep('some_code') etc.
I've been wrestling with godoc and found that "go doc" is more for providing usage help from the command line for instance:
go doc -cmd -u
lists the package comment and any functions (or other entities)
go doc *function*
then shows the documentation for an individual function (or other entity)
It seems there is a related tool called godoc.
godoc also seems to generate html on a per package and function basis.
E.g.
godoc -html hello
Generates html containing the package comment only to stdout
godoc is a really confusing name given we have go doc as well!
How can I create static documentation for the whole project?
This is similar to Godoc, create html for entire package which may have been misinterpreted as asking about documentation for packages rather than projects.
I want a build step I can use in a project that may in principle contain many packages and apps.
is there a canonical way to generate documentation for offline use even using godoc?
Go 1.12 (February 2019) is clearer on that:
godoc and go doc
In Go 1.12, godoc no longer has a command-line interface and is only a web server.
Users should use go doc for command-line help output instead.
go doc now supports the -all flag, which will cause it to print all exported APIs and their documentation, as the godoc command line used to do.
cmd/doc: add -all flag to print all documentation for package
Unlike the one for the old godoc, you need the -u flag to see unexported symbols.
This seems like the right behavior: it's consistent.
I was struggling to do this and finally, the thing that worked for me is
make sure you have "wget" installed(I am using mac, so had to install it using x-code)
log in as root user and modify the file called "robots.txt" to remove the line "Disallow : /" as this prevents wget to download the site recursively. The "robots.txt" file should be in $GOROOT path.
open a cmd and start the godocs server using the below command
godoc -http=:6060
I have my local path configured to this port.
Open another cmd and run the below command.
wget -r -np -N -E -p -k http://localhost:6060/pkg/myproject
you can mention the path of the project to have the html docs downloaded for entire project.
You can try Golds, which is an alternate Go docs generation tool (and a local docs server / code reader).
Under your project directory, you can run any of the following commands to generate HTML docs for your Go project:
golds -gen -nouses -plainsrc -wdpkgs-listing=promoted ./...
golds -gen -nouses -wdpkgs-listing=promoted ./...
golds -gen -wdpkgs-listing=promoted ./...
The first command generates the most compact docs and the last one generates the full docs, which size is 6 times of the compact docs.
BTW, I'm the author of Golds. Hope you this tool would satisfy your need.
This can be also achieved using simple wget command for that. Example: snippet
I have a similar issue with that. I'm using GitLab for my projects and I have decide to create and share with some handy GitLab CI YAML templates for Go projects that will automatically generate a static HTML Go documentation without any external packages: https://gitlab.com/tymonx/gitlab-ci
Example: Go Logger documentation
Two nice features:
Embedded Go source code files
Search box is referencing to GitLab
I am reading on the article how to generate an Apple-like HTML documentation at here. My questions are what the command lines are used for. How can we combine command lines and appledoc xcode project to generate a HTML.
I'm the author of appledoc tool. The tool is intended to be used as answered by Caleb above. Recommended installation method is to clone repository from GitHub, open project in Xcode, build and optionally copy binary to your path as suggested above. Additionally, you must also copy template files required for running the tool to one of predefined paths. All the steps required are described in the readme file on appledoc page on GitHub, see Quick Install section.
There are also other methods for installing - all contribution from users:
You can use install-appledoc.sh script included in the git repository.
There's also homebrew recipe available, although it doesn't install template files to my understanding (see this link).
For any additional questions go to appledoc Google group. I just created it few days ago, so there's no content at the moment of this writing, but feel free to ask questions there.
I haven't used 'appledoc', but from a quick look at the page you linked it appears that it's an open-source command-line utility. So the first step will be to compile the 'appledoc' program itself, and then stick it in a directory that's in your path, such as /usr/local/bin or ~/bin/.
The next step is to try to use it to generate some documentation (assuming that you've already created the markdown files that it consumes). Open a terminal window, navigate to the directory where your files are, and then use the command given at the top of the page that you linked:
appledoc --project-name appledoc --project-company "Gentle Bytes" --company-id com.gentlebytes --output ~/help .
If you want to use 'appledoc' to regenerate your documentation every time you build some project, you can add a "Run Script" build phase to an existing target in your project, or create a new target just for documentation that has nothing but a "Run Script" build phase. Either way, the script in that phase should be shell script containing a command similar to the one above (though you'll probably want to specify the source directory explicitly rather than just using the 'current' directory, i.e. .).
As I found on this post, you can generate a complete HTML documentation of your code with this command line:
appledoc --project-name BabelCPP --project-company "My Name"
--company-id com.mycompany --no-create-docset --output ./doc/ .
The last "." is the path to your code.