Re: Using sphinx-apidoc to automatically generate API reference from docstrings via the autodoc extension...
I copied the global /site-packages/sphinx/templates/apidoc/package.rst_t template to a local folder, and made a nonsense edit. When I built the API docs, the nonsense edit wasn't visible ie. the local templates didn't seem to override the global ones.
Here's my local docs/source directory:
|_ docs
|_ source
|_ templates
| package.rst_t
|_ conf.py
|_ index.rst
conf.py contains this directive:
templates_path = ['templates']
I built the API docs using this command:
sphinx-apidoc -e -M -f --templatedir=./templates -o ./source/autodoc ../myproject
Can anyone see what's going wrong?
I have an AWS S3 website, my yaml builds my site to a dist folder.
What I expect is for my website structure to look like this:
-root
index.html
etc...
Everything works fine, except my website structure ends up looking like this:
-root
-dist
index.html
etc...
This is what my artifacts section of my yaml looks like:
artifacts:
files:
- 'dist/**/*'
It seems, essentially, I do not want the dist folder to be my artifacts, I want the CONTENTS of the dist folder to be the artifacts.
It also seems that the flag to ignore paths flattens the entire system, which I do NOT want. I just want to ignore that one folder dist, and get its contents, including subfolders, etc.
Seems you need the 'base-directory' mapping:
Try this:
artifacts:
base-directory: dist
files:
- '**/*'
I am generating docs using rst/sphinx and am having a problem with images in referenced files.
The include directive works well to bring in rst files, but I am not getting the images that are themselves referenced from the included files.
My structure is like this:
/documentation
/master_doc
/source
pointer_file.rst
and this file calls file.rst:
include:: ../../doc_a/source/file.rst
/documents
/doc_a
/source
/images
picture.jpg
file.rst
includes a figure ref:
.. figure:: images/picture.jpg
When I build from doc_a directory, I get text + image. All good.
But when I build from the master_doc directory, where the include directive comes in, I get only the text and the image is missing in the build.
How can I fix this? I don't want to have to duplicate all my images in both directories, which is the only thing that seems to work at present.
***EDIT: Added detail to project structure above since suggested fix below does not yet work.
I tried all of the following in response to the suggestion in the first comment, and none of it worked:
.. figure:: /documentation/documents/doc_a/source/images/picture.jpg
and
.. figure:: /documents/doc_a/source/images/picture.jpg
and
.. figure:: /doc_a/source/images/picture.jpg
Any other ideas?
Try changing your image file path from relative to absolute.
.. figure:: /doc_a/source/images/picture.jpg
From reStructuredText Primer, Images:
When used within Sphinx, the file name given (here gnu.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or /images/spam.png.
I solved this problem. Thanks to Steve Piercy for asking helpful questions. I had to do 2 things:
move all images to a shared_images folder, at the same relative distance from all doc projects, and
re-organize my project folders to make them siblings.
Now my image refs are all to: ../../../shared_images/.
It works!
The task i'm using looks something like this:
Rake::PackageTask.new("deploy", "0.1.2") do |p|
p.need_tar = true
p.package_files.include("build/**/*")
end
This generates a deploy-0.1.2.zip file. I would like to be able to generate a different package for each folder contained in the build, for example:
build/
|— en/
|— es/
|— de/
|— fr/
Should generate deploy-en-0.1.2.zip, deploy-es-0.1.2.zip, deploy-de-0.1.2.zip, deploy-fr-0.1.2.zip files.
The preconised concept is to locales, not make specific packages
Work with i18n, create a determining code if needed or assuming the locales of the workstation, server how code is executed (in case of CLI, library, etc...)
Otherwise you could create n clones for each languages of your project and create a Rakefile in the root folder how do explicit or recursive call of rake target for each gem building...
you need to do n specific gemspec (one for a specific language) , you also need to write a opy target in your Rakefile to centralized packages because of the differents pkg folders build in each language specific gem folder you create?
Personnaly i think it's not a good idea, you have to maintained n similar copy of the same application ....
I'm starting to learn ruby. I'm also a day-to-day C++ dev.
For C++ projects I usually go with following dir structure
/
-/bin <- built binaries
-/build <- build time temporary object (eg. .obj, cmake intermediates)
-/doc <- manuals and/or Doxygen docs
-/src
--/module-1
--/module-2
-- non module specific sources, like main.cpp
- IDE project files (.sln), etc.
What dir layout for Ruby (non-Rails, non-Merb) would you suggest to keep it clean, simple and maintainable?
As of 2011, it is common to use jeweler instead of newgem as the latter is effectively abandoned.
Bundler includes the necessary infrastructure to generate a gem:
$ bundle gem --coc --mit --test=minitest --exe spider
Creating gem 'spider'...
MIT License enabled in config
Code of conduct enabled in config
create spider/Gemfile
create spider/lib/spider.rb
create spider/lib/spider/version.rb
create spider/spider.gemspec
create spider/Rakefile
create spider/README.md
create spider/bin/console
create spider/bin/setup
create spider/.gitignore
create spider/.travis.yml
create spider/test/test_helper.rb
create spider/test/spider_test.rb
create spider/LICENSE.txt
create spider/CODE_OF_CONDUCT.md
create spider/exe/spider
Initializing git repo in /Users/francois/Projects/spider
Gem 'spider' was successfully created. For more information on making a RubyGem visit https://bundler.io/guides/creating_gem.html
Then, in lib/, you create modules as needed:
lib/
spider/
base.rb
crawler/
base.rb
spider.rb
require "spider/base"
require "crawler/base"
Read the manual page for bundle gem for details on the --coc, --exe and --mit options.
The core structure of a standard Ruby project is basically:
lib/
foo.rb
foo/
share/
foo/
test/
helper.rb
test_foo.rb
HISTORY.md (or CHANGELOG.md)
LICENSE.txt
README.md
foo.gemspec
The share/ is rare and is sometimes called data/ instead. It is for general purpose non-ruby files. Most projects don't need it, but even when they do many times everything is just kept in lib/, though that is probably not best practice.
The test/ directory might be called spec/ if BDD is being used instead of TDD, though you might also see features/ if Cucumber is used, or demo/ if QED is used.
These days foo.gemspec can just be .gemspec --especially if it is not manually maintained.
If your project has command line executables, then add:
bin/
foo
man/
foo.1
foo.1.md or foo.1.ronn
In addition, most Ruby project's have:
Gemfile
Rakefile
The Gemfile is for using Bundler, and the Rakefile is for Rake build tool. But there are other options if you would like to use different tools.
A few other not-so-uncommon files:
VERSION
MANIFEST
The VERSION file just contains the current version number. And the MANIFEST (or Manifest.txt) contains a list of files to be included in the project's package file(s) (e.g. gem package).
What else you might see, but usage is sporadic:
config/
doc/ (or docs/)
script/
log/
pkg/
task/ (or tasks/)
vendor/
web/ (or site/)
Where config/ contains various configuration files; doc/ contains either generated documentation, e.g. RDoc, or sometimes manually maintained documentation; script/ contains shell scripts for use by the project; log/ contains generated project logs, e.g. test coverage reports; pkg/ holds generated package files, e.g. foo-1.0.0.gem; task/ could hold various task files such as foo.rake or foo.watchr; vendor/ contains copies of the other projects, e.g. git submodules; and finally web/ contains the project's website files.
Then some tool specific files that are also relatively common:
.document
.gitignore
.yardopts
.travis.yml
They are fairly self-explanatory.
Finally, I will add that I personally add a .index file and a var/ directory to build that file (search for "Rubyworks Indexer" for more about that) and often have a work directory, something like:
work/
NOTES.md
consider/
reference/
sandbox/
Just sort of a scrapyard for development purposes.
#Dentharg: your "include one to include all sub-parts" is a common pattern. Like anything, it has its advantages (easy to get the things you want) and its disadvantages (the many includes can pollute namespaces and you have no control over them). Your pattern looks like this:
- src/
some_ruby_file.rb:
require 'spider'
Spider.do_something
+ doc/
- lib/
- spider/
spider.rb:
$: << File.expand_path(File.dirname(__FILE__))
module Spider
# anything that needs to be done before including submodules
end
require 'spider/some_helper'
require 'spider/some/other_helper'
...
I might recommend this to allow a little more control:
- src/
some_ruby_file.rb:
require 'spider'
Spider.include_all
Spider.do_something
+ doc/
- lib
- spider/
spider.rb:
$: << File.expand_path(File.dirname(__FILE__))
module Spider
def self.include_all
require 'spider/some_helper'
require 'spider/some/other_helper'
...
end
end
Why not use just the same layout? Normally you won't need build because there's no compilation step, but the rest seems OK to me.
I'm not sure what you mean by a module but if it's just a single class a separate folder wouldn't be necessary and if there's more than one file you normally write a module-1.rb file (at the name level as the module-1 folder) that does nothing more than require everything in module-1/.
Oh, and I would suggest using Rake for the management tasks (instead of make).
I would stick to something similar to what you are familiar with: there's no point being a stranger in your own project directory. :-)
Typical things I always have are lib|src, bin, test.
(I dislike these monster generators: the first thing I want to do with a new project is get some code down, not write a README, docs, etc.!)
So I went with newgem.
I removed all unnecessary RubyForge/gem stuff (hoe, setup, etc.), created git repo, imported project into NetBeans. All took 20 minutes and everything's on green.
That even gave me a basic rake task for spec files.
Thank you all.