标签: rdoc

是否可以将readme.md文件与Rails项目一起使用并将rdoc用作主页？我尝试按如下方式设置我的rake任务,但生成的index.html页面有一个占位符句子.如果我更改为README.rdoc它按预期工作,包括文件的内容.

我也在尝试使用tomdoc,我猜这可能使事情变得复杂,不确定.

RDoc::Task.new :rdoc do |rdoc|
  rdoc.main = "README.md"

  rdoc.rdoc_files.include("README.md", "doc/*.rdoc", "app/**/*.rb", "lib/**/*.rb", "config/**/*.rb")

  rdoc.title = "My Documentation"
  rdoc.options << "--all"
  rdoc.options << "--line-numbers"
  rdoc.markup = "tomdoc"
  rdoc.rdoc_dir = "rdoc"
end

我有一个记录如下的函数:

##
# Searches for street names in the local address database. Returns a list
# of strings, or invokes the block for each result.
#
# @param [String, Hash] query
#
#   Can be:
#
#   - A search string with optinal wildcards. Examples:
#     - "Bærumsv*"
#     - "Fornebuve_en"
#
# @param [Integer] limit
#
#   Limits the amount of results. See {#search_street_addresses} for usage
#   examples.
#
# @return [Array<String>]
#
#   A sorted array of street …

我正在使用Doxygen为C++项目创建内部文档.我有Doxygen包括方法的来源等,但这使得页面很难扫描.我希望它的行为类似于rdoc,并将源隐藏在默认情况下折叠的块中.

我认为这HTML_DYNAMIC_SECTIONS可能让我这样做,但唉,更改日志说该选项只会影响图表和图形.

也许我可以通过编辑来做到这一点LAYOUT_FILE？

无论如何,聪明的人,我怎么能强迫Doxygen生成可折叠的代码段？

我刚刚安装了rvm然后使用以下命令修改了3.1rc5:

gem install rails --pre

但是在"安装ri文档"和RDoc文档之后我遇到了一些错误:

Successfully installed <bunch of things>
30 gems installed
Installing ri documentation for multi_json-1.0.3...
Installing ri documentation for activesupport-3.1.0.rc5...
Installing ri documentation for builder-3.0.0...
unable to convert "\xF1" from ASCII-8BIT to UTF-8 for README, skipping
unable to convert "\xF1" from ASCII-8BIT to UTF-8 for README.rdoc, skipping
Installing ri documentation for i18n-0.6.0...
Installing <tons more documentation>
Installing ri documentation for rails-3.1.0.rc5...
file 'lib' not found
Installing RDoc documentation for multi_json-1.0.3...
Installing RDoc documentation for activesupport-3.1.0.rc5...
Installing …

只是预警:我是一个铁杆菜鸟.

当我跑:

rake db:migrate

我收到了这个弃用警告:

WARNING: 'require 'rake/rdoctask'' is deprecated.  Please use 'require 'rdoc/task' (in RDoc 2.4.2+)' instead.
    at /Users/username/Code/rails/appname/rake/ruby/1.9.1/gems/rake-0.9.2.2/lib/rake/rdoctask.rb

我正在使用:

• Rails 3.0.1
• 耙0.9.2.2
• RSpec 2.0.1
• RDoc 3.12

如果我卸载rake 0.9.2.2并使用0.8.7就没有警告,但我宁愿不把它作为解决方案.

在谷歌搜索之后,许多网站都说我需要更新我的Rakefile中的一行(基本上需要更改'rake/rdoctask'来要求'rdoc/task').但是,我的Rakefile看起来像这样:

require File.expand_path('../config/application', __FILE__)
require 'rake'

AppName::Application.load_tasks

没有要求替换的声明.当我添加require'rdoc/task'时,它没有任何效果.当我在项目中搜索已弃用的'rake/rdoctask'时,没有结果.为什么rails抱怨？

编辑:不确定是否重要,但这是我的gemfile:

source 'http://rubygems.org'

gem 'rails', '3.0.1'
gem 'sqlite3-ruby', :require => 'sqlite3'

group :development, :test do
   gem 'rspec-rails', '2.0.1'
   gem 'annotate-models', '1.0.4'
end

group :test do
   gem 'rspec', '2.0.1'
   gem 'webrat', '0.7.1'
   gem 'spork', '0.8.4'
end

我有Ubuntu 11.10并使用rvm和ruby 1.9.2.我完全按照这个安装Ruby:http://blog.sudobits.com/2011/10/27/how-to-install-ruby-on-rails-in-ubuntu-11-10/

我用它生成文档

rvm docs generate

这似乎适用于一次终端会话,但是一旦我退出并重新开始,我必须再次生成文档,否则我得到Nothing is Known错误这需要很长时间,所以我宁愿不必每次我开始终端会话时都会生成文档.

有什么办法可以永久保存文档吗？

对此有一些类似的问题 - 但我没有生成文档或使用它们的问题,只是保持它们的安装.

我正在将从RDoc维护的rubygem切换到YARD文档.但是,代码中有一些关键注释只需要保留在代码中,不应该出现在文档中.例如:

##
# SomeClass documentation here.
#--
# CRITICAL comment that should be in the code but not in the documentation,
#          and must be at this particular spot in the code.
#++
# more documentation that follows the critical comment block, but this part 
# should be in the generated documentation
class SomeClass
    ...
end

RDoc尊重#--和#++门,但YARD没有.什么(如果存在)是在YARD标记中做类似事情的语法？

我有一个客户端gem,我将通过rubygems分发业务客户端.宝石客户有cca.十几个gem依赖项,当它被安装时,由于每个gem的生成rdoc和安装它需要很长时间ri.

客户端是业务用户,他们没有使用rdoc/ri,我正在寻找一种方法来禁用通过.gemspec或Gemfile.我熟悉一个利用系统文件.gemrc来禁用rdoc/ri 的解决方案.但这是不可接受的解决方案,因为我希望我的安装很简单,因为输入:

gem install foo

我正在尝试在我的 YARD 文档中创建一些链接。我可以得到一个 HTTP 链接：

# I like {http://stackoverflow.com Stackoverflow}

呈现为

<p>I like <a href="http://stackoverflow.com">Stackoverflow</a></p>

但是一个电子邮件链接：

# You can email the {mailto:bugs@myproject.com bugs} list

给我一个警告：

[warn]: In file `':: Cannot resolve link to mailto:bugs@myprojectmailto:bugs@myproject.com from text:

并呈现为

<p>You can email the <tt>bugs</tt> list</p>

我已经尝试过链接的常规 RDoc 语法：

bugs[mailto:bugs@myproject.com]

但 YARD 似乎忽略了这一点。有谁知道更可靠的语法？

这些错误意味着什么？

[root@localhost config]# gem install bluecloth
Building native extensions.  This could take a while...
ERROR:  Error installing bluecloth:
    ERROR: Failed to build gem native extension.

/usr/bin/ruby extconf.rb
can't find header files for ruby.


Gem files will remain installed in /usr/lib64/ruby/gems/1.8/gems/bluecloth-2.0.7 for 
inspection.
Results logged to /usr/lib64/ruby/gems/1.8/gems/bluecloth-2.0.7/ext/gem_make.out
[root@localhost config]# 

还有这个

[root@localhost config]# gem install chronic
Successfully installed json_pure-1.4.3
Successfully installed rubyforge-2.0.4
Successfully installed hoe-2.6.0
Successfully installed chronic-0.2.3
4 gems installed
/usr/lib64/ruby/gems/1.8/gems/rdoc-2.5.8/lib/rdoc/ruby_lex.rb:67: warning: 
parenthesize argument(s) for future version
ERROR:  While executing gem …