我在一个复杂的应用程序上工作,不同的团队在自己的模块上工作,有一定程度的重叠.前段时间我们设置了一个Mediawiki实例,部分是在我的提示下.我很难让人们真正使用它,更不用说贡献了.

我可以看到共享信息有很多好处.它至少可以减少我们重新发明轮子的次数.

维基的结构不是很好,但只要你可以搜索你需要的东西,我不确定这是一个问题.

任何提示？

在C++中创建公共头文件时,您认为最佳做法是什么？

1. 头文件是否应该包含没有,简短或大量的文档？我已经看到了一切,从几乎没有文档(依靠一些外部文档),以大规格不变,有效参数,返回值等我不知道正是我喜欢的,大的文件是好的,因为你一直访问它从你的编辑器中,另一方面以非常简短的文档,头文件往往可以显示在文本给人什么是可能与类做一个更好的概述的一个或两个页面的完整接口.

2. 假设我选择简短或大量的文档.我想要类似于javadoc的东西,其中我记录了返回值,参数等.在c ++中,最好的约定是什么？据我所知,doxygen在java doc风格的文档中做得很好,但在使用javadoc样式文档之前,我是否应该注意其他任何约定和工具？

回到我的C#天,我喜欢使用名为"GhostDoc"的Visual Studio扩展.现在我已经被用作Java开发人员,我正在使用Eclipse.我可以在没有推断文档的情况下生活,但我想做的是智能地"修复"我的文档.例如,假设我有以下方法:

/**
 * Gets a collection of {@link Foo} objects
 * @param bar The bar level
 * @param baz The bazziness
 */
public Collection<Foo> getFoos(int bar, int baz)
{
    // Do something cool
}

后来在开发中我意识到允许我的方法的使用者传入qux值会很有用.不仅如此,将它作为第一个参数最有意义.此外,我将使用该方法抛出超级有用的FooBarException.所以现在我的方法看起来像这样:

/**
 * Gets a collection of {@link Foo} objects
 * @param bar The bar level
 * @param baz The bazziness
 */
public Collection<Foo> getFoos(String qux, int bar, int baz) throws FooBarException
{
    // Do something cool
}

作为一名优秀的开发人员,我希望我的更改能够反映在我的JavaDoc中.在GhostDoc中,我可以点击我的文档快捷键,它会添加新的东西,而不会打扰旧的东西.在Eclipse中,它呈现了一整套新的JavaDoc,我必须做一堆复制面食.我怎么能自动将新@param,@exception以及缺少@returns参数到我的JavaDoc不失,我目前拥有的JavaDoc的？

在我的Sphinx文档中,当我在重组文本中引用它们时,我想显示键盘键的图片.

例如,如果我说:点击Enter键.我想在线显示Enter键的图片,而不是单词Enter.

我在许多教程中都看到过这种图形,用于引用键盘按键,菜单选项等.他们是如何做到这一点的？我可以在Sphinx中这样做吗？

因此,我在静态土地上花了大量时间后开始使用Python.我已经看到一些项目使得"接口"实际上只是没有任何实现的类.之前,我嘲笑这个想法,忽略那些项目的那一部分.但现在,我开始热衷于这个想法了.

我们很清楚,Python中的界面看起来像这样:

class ISomething(object):
    def some_method():
        pass
    def some_other_method(some_argument):
        pass

请注意,您没有将self传递给任何方法,因此要求重写该方法以进行调用.我认为这是一种很好的文档和完整性测试形式.

那么每个人对这个想法的看法是什么？我做过的所有C#编程都被洗脑了,还是这个好主意？

背景资料

我正在为我公司的开发人员设置一种方法来共享有关我们各种内部系统的文档和信息.这可能包括有助于提高新员工速度的信息,以及用户对系统及其解决方案的常见问题的描述.

对我来说这似乎是一个理想的维基工作,由于我们公司只能托管ASP.NET应用程序,所以我开始研究可用的ASP.NET wiki.ScrewTurn Wiki似乎是最合适的,它功能非常齐全,有几个可用的插件对我的情况很有用,包括语法高亮和AD集成.

然而,在启动将ScrewTurn部署到我们的Intranet的过程时,突然想起,嘿,Sharepoint 2007有一个wiki,而且由于我们已经设置了Sharepoint,我们不能只使用它吗？我对Sharepoint"wiki"进行了一些评估(在引号中,因为它几乎没有资格),并且能够证明它由于它的许多缺陷而不适合,我将不在此列出.

现在,在这一点上,有人建议我可能根本不需要维基,我们不能只在Word文档中执行所有操作并使用Sharepoint的文档管理功能吗？

实际的问题

所以我正在寻找的是一些额外的弹药,最好是有经验的人.在内部开发人员文档的上下文中,Sharepoint难以或不可能的事例是什么？什么是wiki更好？嘿,我心胸开阔,Sharepoint更好的是什么？

什么使得部署维基而不是简单地使用我们已经拥有的东西值得？

我花了最后一小时搜索官方Google Voice API文档,但除了一堆API包装器之外找不到任何东西(insert your favorite programming language here).

是否存在Google Voice API的文档？

我正在尝试为实际项目创建测试Python项目的文档.我的系统:Win7 64位,python 2.7.5 64位.

我的项目名称是testDoc.它包括名为t的 python pakage,它包含2个模块t1和t2和__init__.py.

__init__.py 包含:

import t1
import t2

t1.py包含:

'''
Created on 27  2013

@author: 
'''

class MyClass(object):
    '''
    Hi
    '''


    def __init__(self,selfparams):
        '''
        Constructor
        '''
        pass

要创建文档,我在testDoc的命令行中运行:

sphinx-apidoc -A "me" -F -o docs .

Sphinx根据Sphinx文档创建了许多文件.然后,conf.py被修改

sys.path.insert(0, os.path.abspath(absolute path to testDoc))

我输入docs文件夹并输入

make html

并获得以下错误输出:

Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
building …

我在http://code.google.com/p/pylevenshtein/找到了一个实现Levenshtein函数(距离,比率等)的伟大python库,但该项目似乎无效,文档无处可寻.我想知道是否有人比我更了解并且能指出我的文档.

问题

在尝试为可重用的Django应用程序生成sphinx文档时,我发现了以下snafoo.当sphinx解析model.py代码时,它会被试图访问Django 项目设置的代码所阻挠.由于这是一个独立/可重用的应用程序,因此没有提供这些设置的主项目,即没有ROOT/PROJECT/PROJECT/settings.py文件.

建立

为了清楚起见,这就是我所做的.遍历通常的项目文件夹cd ROOT/PROJECT并创建一个生成以下结构的应用程序 django-admin startapp APPLICATION

/ROOT/
  /PROJECT/
    /APPLICATION/ 
      admin.py
      apps.py
      models.py
      tests.py
      views.py

注意:没有/ROOT/PROJECT/PROJECT/*.py文件,因为我没有导航到根文件夹cd root并使用通常可能的方式创建项目django-admin createproject.

接下来创建sphinx文档,spinx-quickstart docs生成以下附加结构.

/ROOT/
  /PROJECT/
    /docs/
      /source/ 
        ...
        conf.py
      make.bat

那就是文档旁边的文档APPLICATION.

题

如果没有文件,我可以放置什么conf.py来正确加载应用程序settings.py？

家庭作业

在尝试解决这个问题时,我已经仔细阅读了许多SO问题,博客和Django文档,但没有找到简洁的解决方案.因为这已经被问了几次之前我想要激励它不会被重复关闭,如果建议的副本中的答案使用其中一个片段作为解决方案.

• 失败了 AppRegistryNotReady

  from django.conf import settings
  settings.configure()
  

  Run Code Online (Sandbox Code Playgroud)

• 类似于第一种失败方法即发射 AppRegistryNotReady

  from django.conf import settings …

  Run Code Online (Sandbox Code Playgroud)