Astropy叙事风格指南：供投稿人使用的写作资源¶

这个风格指南的目的是为Astropy社区提供一套风格和格式指南，在编写Astropy文档时可以参考。遵循该风格指南中提供的指导方针，将为Astropy的文档带来更大的一致性和清晰性，支持Astropy开发一个通用的天文学核心包的任务，并培育一个可互操作的天文软件包的生态系统。

这本风格指南是按写作主题的字母顺序组织的，每个部分都有用法示例，最后是音调和格式准则。

缩写¶

将i.e.和e.g.等缩写放在括号内，括号后面跟着逗号。或者，考虑使用“that is”和“example”，前面加一个em破折号或分号，后跟一个逗号，或者包含在em破折号中。

实例¶

修改帧中数据的唯一方法是使用 data 属性，而不是帧上组件的别名（即，以下操作将不起作用）。
没有计划支持更复杂的进化（例如，非惯性系或更复杂的进化），因为这超出了 astropy 核心。
一旦你有了一个坐标对象，你就可以访问这个坐标的组件——例如，RA或Dec——来获得完整坐标的字符串表示。

对于一般用途和科学术语，只有当缩略语在天文学界广为人知和广泛使用时才使用缩写。对于不太常见的科学术语，或特定领域的术语，请写出该术语或链接到解释资源。在决定某个东西是否应该缩写时，一个好的经验法则是：当有疑问时，把它写出来。

实例¶

1D、2D等优于一维、二维等。
国际单位制和CGS等单位可以缩写为科学界更常见的单位。
白矮星应该完全写出来，而不是缩写为WD。
使用首字母缩略词的组织或其他专有名词的名称应写为其已知的首字母缩略词，但应带有指向网站或资源的超链接以供参考，例如， CODATA .

资本化¶

在纯文本中，所有专有名词（名称）都要大写，除非是指包/代码名，在这种情况下使用小写和双反撇号。Astropy capitaled是指Astropy项目，而 astropy 小写和反撇号表示核心包。

实例¶

遵循Astropy准则来编写代码。
附属软件包是天文学相关的软件包，不属于 astropy 核心包。
提供一个代码示例以及操作系统和Python的详细信息， numpy 和 astropy 您正在使用的版本。

在文献资料中，标题大小写优先于标题，意思是首字母大写，最后大写，标题中的所有主要单词，但小写冠词（the，a，an），介词（at，to，up，down，with，In等）和常见的并列连词（and，but，for，or）。对于较长的示例标题，句子大小写是可以接受的。

实例¶

建造和安装
没有数据的帧
贡献代码检查表
Astropy 指南
进口 astropy 和分装
示例：使用速度计算不同时期的天空位置

在教程和其他学习材料中，结构化介绍/模板部分的标题首选标题大小写，但在教程中，句子大小写（即仅大写第一个单词和专有名词）可用于指定不同学习/代码部分的较长标题。

收缩¶

不要在正式文件材料中使用缩略语。

实例¶

如果你做的改变 astropy 性能，考虑添加性能基准。
不需要包含变更日志条目。

在所有其他材料中，只有在时态可能混淆的情况下才避免使用缩略语，例如“她走了”和“她走了”等等。

断字¶

短语形容词/复合修饰语放在名词之前应该连字符以避免混淆。

实例¶

天文学相关软件包。
天体学为天文学界提供可持续的高水平教育。

用连字符连接的复合词应在纯文本中包含连字符，但在代码中不应包含连字符。

例子¶

别忘了仔细检查你的格式。

数字¶

对于后跟单位或作为名称一部分的数字，请使用数字。

实例¶

1弧分
32度
盖亚数据发布2目录
1D、2D等优于一维、二维等。

对于所有其他的整数，请遵循美联社的风格：拼出1到9的数字，用数字表示10或更高的数字，用数字组合表示数百万、数十亿和万亿。

实例¶

有两种方法可以构建Astropy文档。
遵循以下11个步骤。
测量大约20亿颗恒星的天体测量。

对于随意的表达，请拼出数字。

例子¶

一幅画胜过千言万语。

标点符号¶

为了保持Astropy材料的一致性，将编辑非美国标点符号以反映美国人对标点符号的偏好。

圆括号 ：属于附加材料的标点符号将放在右括号内，但逗号表示插入材料后面的小停顿，以及插入材料包含在另一个句子中的句点除外。

实例¶

（有关完整的参与者指南，请参阅我们的文档。）
一旦您打开拉取请求（应该针对 master 请确保包括以下内容。
在某些情况下，大多数必需的功能都包含在一个类（或几个类）中。

引号：句点和逗号将放在右引号内，无论是双引号还是单引号。

实例¶

这些术语中最主要的是“坐标系”的概念
因为“坐标系”的这些含义可能会混淆 coordinates 尽可能避免使用此术语。

连字符vs.En破折号vs.Em破折号

连字符（-）应该用于短语形容词和复合词（参见 Hyphenation 以上）。

破折号（–更长）应用于数字范围（日期、时间、页面）或替换单词“to”或“through”，短划线周围不带空格。

实例¶

见第14-18章。
我们已经封锁了2019年3月至2019年5月，以开发新版本。

Em破折号（-longest）可以用来代替逗号、圆括号或冒号来分隔放大或解释元素。在Astropy材质中，遵循美联社（Associated Press，AP）风格，即在每个em破折号的两边都要有空格。

实例¶

在创建角度对象时，可以使用几种类型的输入角度-数组、标量、元组、字符串。
角度对象的创建支持多种输入角度类型-数组、标量、元组、字符串等。

拼写¶

为了保持Astropy材料的一致性，将编辑非美国拼写以反映美国人的拼写偏好。

例子¶

时间和日期¶

用数字表示确切的时间。使用24小时制来表达准确的时间。为了保持Astropy材质的一致性，所有精确时间的实例都将被编辑以反映24小时时间系统的偏好。

例子¶

演讲15点开始。

以ISO 8601格式的数字表示具体日期，年-月-日。

例子¶

盖亚任务的数据于2018年4月25日发布。

关于声音和音调的注释¶

在叙述部分的所有阿谀奉承的材料中，请遵循这些声音和音调指南。

用现在时态写。

例子¶

在下一节中，我们将制作一个情节。。。
测试您的版本 astropy 运行正常。。。

使用第一人称的复数形式。

例子¶

我们做了很长的路，但接下来我们可以尝试短的路。。。

用一般代词“you”代替“one”

例子¶

你可以访问帧上的任何属性。。。

总是避免无关的或轻视的词，如“显然”、“容易”、“简单”、“公正”或“直截了当”。避免无关的短语，如“我们只需再做一件事。”

避免让读者担心的词语或短语。相反，使用积极的语言来建立对所学技能的信心。

实例¶

作为最佳实践。。。
一种推荐的方法。。。
要记住的一点是。。。

沿着这些思路，使用“警告”指令只注意代码中的限制，而不是隐含在读者技能或知识方面的限制。

文档vs.教程vs.指南¶

文档¶

语气：学术的，稍微正式一点。

在章节标题中使用标题大小写。
不要收缩。

教程¶

语气：学术，但不那么正式，更友好。

在介绍性/模板标题中使用标题大小写，对于学习/示例部分标题，切换到句子大小写。
章节标题应使用祈使语气来形成命令或请求（例如，“下载数据”）。
只要时态清晰，就可以使用缩略语。

指南¶

语气：学术，但不那么正式，更友好。

在介绍性/模板标题中使用标题大小写，对于学习/示例部分标题，切换到句子大小写。
只要时态清晰，就可以使用缩略语。

格式准则¶

Astropy文档是使用Sphinx文档生成器以RestructedText编写的。在格式化文档文件的不同部分时，请遵循以下指导原则，以保持Astropy RST文件的节标题层次结构的一致性。

RestructedText文件中的节标题是通过在节标题下加下划线（也可以在上面加上与文本长度相同的标点字符）来创建的。

实例¶

*************************
This is a Chapter Heading
*************************

This is a Section Heading
=========================

虽然没有正式指定字符来创建标题级别的层次结构，但由于层次渲染是由连续的标题决定的，因此在格式化Astropy文档文件时，建议遵循以下约定：

#带上划线，部分*带上划线，章节=，章节-，分节-，子章节-，段落

这些指南遵循Sphinx在 Sections 其StructuredText Primer和Python在 7.3.6. Sections 它的风格指南的一部分。

其他写作资源¶

在编写Astropy文档时，其他一些有用的资源包括：

导航