Commit Graph

12 Commits

Author SHA1 Message Date
Janne Heß
fcc95ff817 treewide: Fix all Nix ASTs in all markdown files
This allows for correct highlighting and maybe future automatic
formatting. The AST was verified to work with nixfmt only.
2024-03-28 09:28:12 +01:00
Anderson Torres
e671d3bbbd Nix docs: remove with lib; from example code
Following [Best Practices](https://nix.dev/guides/best-practices#with-scopes),
`with` is a problematic language construction and should be avoided.

Usually it is employed like a "factorization": `[ X.A X.B X.C X.D ]` is written
`with X; [ A B C D ]`.

However, as shown in the link above, the syntatical rules of `with` are not so
intuitive, and this "distributive rule" is very selective, in the sense that
`with X; [ A B C D ]` is not equivalent to `[ X.A X.B X.C X.D ]`.

However, this factorization is still useful to "squeeze" some code, especially
in lists like `meta.maintainers`.

On the other hand, it becomes less justifiable in bigger scopes. This is
especially true in cases like `with lib;` in the top of expression and in sets
like `meta = with lib; { . . . }`.

That being said, this patch removes most of example code in the current
documentation.

The exceptions are, for now
- doc/functions/generators.section.md
- doc/languages-frameworks/coq.section.md

because, well, they are way more complicated, and I couldn't parse them
mentally - yet another reason why `with` should be avoided!
2024-03-06 11:40:09 -03:00
Arnout Engelen
97b0ae26f7
doc: avoid 'simply' (#266434)
While the word 'simply' is usually added to encourage readers, it often has the
opposite effect and may even appear condescending, especially when the reader
runs into trouble trying to apply the suggestions from the documentation. It is
almost always an improvement to simply drop the word from the sentence.

(there are more possible improvements like this, we can apply those in separate
PRs)
2023-11-09 21:48:05 +01:00
Weijia Wang
3bf9e65881 doc/maven: add stable-maven-plugins back 2023-08-01 16:00:52 +02:00
Tomo
48bbc6d964 doc/maven: prefer maven.buildMavenPackage over mvn2nix
Manually calling `mvn2nix` was the preferred way of building
Java apps that use Maven, but `maven.buildMavenPackage` is now the
preferred way.
2023-08-01 10:19:26 +02:00
Tillerino
9def595d00
doc: add a note about automatic maven upgrades (#238774) 2023-06-30 16:59:23 +03:00
Artturin
c87635d917 doc: move makeWrapper to nativeBuildInputs from buildInputs
makeWrapper in buildInputs breaks cross-compilation with error: attribute 'runtimeShell' missing
2022-07-14 22:08:56 +03:00
Jan Tojnar
6ecc641d08
doc: prepare for commonmark
We are still using Pandoc’s Markdown parser, which differs from CommonMark spec slightly.

Notably:
- Line breaks in lists behave differently.
- Admonitions do not support the simpler syntax https://github.com/jgm/commonmark-hs/issues/75
- The auto_identifiers uses a different algorithm – I made the previous ones explicit.
- Languages (classes) of code blocks cannot contain whitespace so we have to use “pycon” alias instead of Python “console” as GitHub’s linguist

While at it, I also fixed the following issues:
- ShellSesssion was used
- Removed some pointless docbook tags.
2021-06-07 06:34:59 +02:00
V
7616206b77
doc: add function argument order convention (#110060)
* doc: add function argument order convention

Ordering by usage is the de facto ordering given to arguments. It's
logical, and makes finding argument usage easier. Putting lib first is
common in NixOS modules, so it's reasonable to mirror this in nixpkgs
proper. Additionally, it's not a package as such, has zero dependencies,
and can be found used anywhere in a derivation.

* doc: clean up usage of lib
2021-01-20 19:07:16 -05:00
Profpatsch
b0c1583a0b doc: stdenv.lib -> lib
Part of: https://github.com/NixOS/nixpkgs/issues/108938

Changing the documentation to not refer to stdenv.lib is the first
step to make people use it directly.
2021-01-11 09:52:27 +01:00
Ryan Mulligan
b8344f9e5c doc: explicit Markdown anchors for top-level headings; remove metadata
I used the existing anchors generated by Docbook, so the anchor part
should be a no-op. This could be useful depending on the
infrastructure we choose to use, and it is better to be explicit than
rely on Docbook's id generating algorithms.

I got rid of the metadata segments of the Markdown files, because they
are outdated, inaccurate, and could make people less willing to change
them without speaking with the author.
2021-01-01 10:02:57 -08:00
Farid Zakaria
b9321adf1e documentation: add documentation for maven
Add nice markdown documentation for how to use mvn2nix plugin and the
buildMaven function within nixpkgs.

Update doc/languages-frameworks/maven.md

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>

Apply suggestions from code review

Co-authored-by: Doron Behar <doron.behar@gmail.com>

Apply suggestions from code review

Co-authored-by: Doron Behar <doron.behar@gmail.com>

Apply suggestions from code review

Co-authored-by: Doron Behar <doron.behar@gmail.com>
2020-11-03 09:23:05 -08:00