Skip to content

Commit f268c6c

Browse files
glynosglynos
authored
Updated library documentation (#67)
* Rewrote documentation * Updated remaining samples
1 parent 9a4ea85 commit f268c6c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+601
-312
lines changed

‎CHANGELOG.md

+12
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
44
The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
55
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
66

7+
## [1.7.0] - 2020-04-16
8+
9+
### Added
10+
11+
- A function to convert an encoded domain to Unicode
12+
- Functions to convert a query string to and from a JSON object
13+
- A lot more documentation
14+
15+
### Changed
16+
17+
- Code style changes
18+
719
## [1.6.0] - 2020-04-12
820

921
### Added

‎CMakeLists.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ cmake_minimum_required(VERSION 3.14)
88

99
project(
1010
skyr-url
11-
VERSION 1.6.0
11+
VERSION 1.7.0
1212
HOMEPAGE_URL https://cpp-netlib.github.io/url
1313
DESCRIPTION "A C++ library that implements the WhatWG URL specification"
1414
LANGUAGES CXX

‎README.md

+3-5
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,7 @@ Windows:
213213
## License
214214

215215
This library is released under the Boost Software License (please see
216-
http://boost.org/LICENSE_1_0.txt or the accompanying LICENSE_1_0.txt
216+
http://boost.org/LICENSE_1_0.txt or the accompanying [LICENSE_1_0.txt](LICENSE_1_0.txt)
217217
file for the full text).
218218

219219
## Why *skyr*?
@@ -224,9 +224,7 @@ itself was randomly chosen.
224224
## Contact
225225

226226
Any questions about this library can be addressed to the cpp-netlib
227-
[developers mailing list]. Issues can be filed using Github at
228-
http://github.com/cpp-netlib/url/issues.
227+
[developers mailing list]([email protected]). Issues can
228+
be filed on our [GitHub page](http://github.com/cpp-netlib/url/issues).
229229

230230
You can also contact me via Twitter [@glynos](https://twitter.com/glynos).
231-
232-
[developers mailing list]: [email protected]

‎docs/CMakeLists.txt

+14-56
Original file line numberDiff line numberDiff line change
@@ -11,33 +11,22 @@ find_package(Doxygen REQUIRED)
1111
find_package(Pandoc REQUIRED)
1212
find_package(Sphinx REQUIRED)
1313

14-
set(DOC_FILES
14+
# Copy RST files
15+
foreach(doc_file
1516
_build
1617
_static
1718
_templates
1819
index.rst
19-
unicode.rst
20-
idna.rst
21-
domain.rst
22-
encoding.rst
23-
encoding_u8_view.rst
24-
encoding_u16_view.rst
25-
encoding_byte_transform.rst
26-
encoding_u16_transform.rst
27-
encoding_u32_transform.rst
2820
url.rst
29-
url_class.rst
30-
url_record.rst
31-
url_error_codes.rst
32-
url_search_parameters.rst
33-
)
34-
35-
# Copy RST files
36-
foreach(doc_file ${DOC_FILES})
21+
core.rst
22+
domain.rst
23+
network.rst
24+
percent_encoding.rst
25+
filesystem.rst
26+
json.rst)
3727
file(COPY ${doc_file} DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
3828
endforeach()
3929

40-
# Generate API documentation using Doxygen
4130
configure_file(
4231
Doxyfile.in
4332
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
@@ -47,48 +36,17 @@ configure_file(
4736
${CMAKE_CURRENT_BINARY_DIR}/conf.py @ONLY)
4837

4938
add_custom_target(
50-
doxygen ALL
39+
doc ALL
5140
COMMAND
5241
${DOXYGEN}
53-
WORKING_DIRECTORY
54-
${CMAKE_CURRENT_BINARY_DIR}
55-
COMMENT
56-
"Generating documentation with Doxygen"
57-
)
58-
59-
# Convert markdown to RST
60-
SET(
61-
GENERATED_FROM_MARKDOWN
62-
readme.rst
63-
changelog.rst
64-
)
65-
66-
foreach (file_name ${GENERATED_FROM_MARKDOWN})
67-
skyr_remove_extension(${file_name} basename)
68-
string(TOUPPER ${basename} basename_upper)
69-
set(target ${basename})
70-
string(PREPEND target "doc_")
71-
add_custom_target(
72-
${target}
73-
pandoc ${PROJECT_SOURCE_DIR}/${basename_upper}.md -f markdown -t rst -s -o ${CMAKE_CURRENT_BINARY_DIR}/${file_name}
74-
WORKING_DIRECTORY
75-
${CMAKE_CURRENT_BINARY_DIR}
76-
BYPRODUCTS
77-
${CMAKE_CURRENT_BINARY_DIR}/${file_name}
78-
COMMENT
79-
"Generating RST file with pandoc" VERBATIM
80-
)
81-
endforeach()
82-
83-
# Bring it all together using Sphinx
84-
add_custom_target(
85-
doc ALL
42+
COMMAND
43+
${PANDOC_EXECUTABLE} ${PROJECT_SOURCE_DIR}/CHANGELOG.md -f markdown -t rst -s -o ${CMAKE_CURRENT_BINARY_DIR}/changelog.rst
8644
COMMAND
8745
${SPHINX_EXECUTABLE} -M html ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_BINARY_DIR}
46+
COMMAND
47+
touch ${CMAKE_CURRENT_BINARY_DIR}/html/.nojekyll
8848
WORKING_DIRECTORY
8949
${CMAKE_CURRENT_BINARY_DIR}
90-
DEPENDS
91-
doxygen ${GENERATED_FROM_MARKDOWN}
9250
COMMENT
93-
"Generating documentation with Sphinx"
51+
"Generating documentation with Doxygen and Sphinx"
9452
)

‎docs/Doxyfile.in

+8-18
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ PROJECT_NAME = "Skyr URL"
3838
# could be handy for archiving the generated documentation or if some version
3939
# control system is used.
4040

41-
PROJECT_NUMBER =
41+
PROJECT_NUMBER = @skyr-url_VERSION@
4242

4343
# Using the PROJECT_BRIEF tag one can provide an optional one line description
4444
# for a project that appears at the top of each page and should give viewer a
@@ -829,23 +829,13 @@ WARN_LOGFILE =
829829
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
830830
# Note: If this tag is empty the current directory is searched.
831831

832-
INPUT = @PROJECT_SOURCE_DIR@/include/skyr/config.hpp \
833-
@PROJECT_SOURCE_DIR@/include/skyr/version.hpp \
834-
@PROJECT_SOURCE_DIR@/include/skyr/unicode.hpp \
835-
@PROJECT_SOURCE_DIR@/include/skyr/unicode/domain.hpp \
836-
@PROJECT_SOURCE_DIR@/include/skyr/unicode/idna.hpp \
837-
@PROJECT_SOURCE_DIR@/include/skyr/unicode/errors.hpp \
838-
@PROJECT_SOURCE_DIR@/include/skyr/unicode/ranges/transforms/byte_transform.hpp \
839-
@PROJECT_SOURCE_DIR@/include/skyr/unicode/ranges/transforms/u16_transform.hpp \
840-
@PROJECT_SOURCE_DIR@/include/skyr/unicode/ranges/transforms/u32_transform.hpp \
841-
@PROJECT_SOURCE_DIR@/include/skyr/unicode/ranges/views/u8_view.hpp \
842-
@PROJECT_SOURCE_DIR@/include/skyr/unicode/ranges/views/u16_view.hpp \
843-
@PROJECT_SOURCE_DIR@/include/skyr/url.hpp \
844-
@PROJECT_SOURCE_DIR@/include/skyr/url/url_error.hpp \
845-
@PROJECT_SOURCE_DIR@/include/skyr/url/url_parse.hpp \
846-
@PROJECT_SOURCE_DIR@/include/skyr/url/url_record.hpp \
847-
@PROJECT_SOURCE_DIR@/include/skyr/url/url_search_parameters.hpp \
848-
@PROJECT_SOURCE_DIR@/include/skyr/url/url_serialize.hpp
832+
INPUT = @PROJECT_SOURCE_DIR@/include/skyr/ \
833+
@PROJECT_SOURCE_DIR@/include/skyr/core/ \
834+
@PROJECT_SOURCE_DIR@/include/skyr/domain/ \
835+
@PROJECT_SOURCE_DIR@/include/skyr/network/ \
836+
@PROJECT_SOURCE_DIR@/include/skyr/percent_encoding/ \
837+
@PROJECT_SOURCE_DIR@/include/skyr/filesystem/ \
838+
@PROJECT_SOURCE_DIR@/include/skyr/json/
849839

850840
# This tag can be used to specify the character encoding of the source files
851841
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

‎docs/conf.py.in

+69-2
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,75 @@ html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
9191
# further. For a list of options available for each theme, see the
9292
# documentation.
9393
#
94-
# html_theme_options = {}
95-
94+
html_theme_options = {
95+
# Navigation bar title. (Default: ``project`` value)
96+
'navbar_title': "Skyr URL",
97+
98+
# Tab name for entire site. (Default: "Site")
99+
'navbar_site_name': "Site",
100+
101+
# A list of tuples containing pages or urls to link to.
102+
# Valid tuples should be in the following forms:
103+
# (name, page) # a link to a page
104+
# (name, "/aa/bb", 1) # a link to an arbitrary relative url
105+
# (name, "http://example.com", True) # arbitrary absolute url
106+
# Note the "1" or "True" value above as the third argument to indicate
107+
# an arbitrary url.
108+
'navbar_links': [
109+
("GitHub", "https://github.com/cpp-netlib/url/", True),
110+
],
111+
112+
# Render the next and previous page links in navbar. (Default: true)
113+
'navbar_sidebarrel': True,
114+
115+
# Render the current pages TOC in the navbar. (Default: true)
116+
'navbar_pagenav': True,
117+
118+
# Tab name for the current pages TOC. (Default: "Page")
119+
'navbar_pagenav_name': "Page",
120+
121+
# Global TOC depth for "site" navbar tab. (Default: 1)
122+
# Switching to -1 shows all levels.
123+
'globaltoc_depth': 2,
124+
125+
# Include hidden TOCs in Site navbar?
126+
#
127+
# Note: If this is "false", you cannot have mixed ``:hidden:`` and
128+
# non-hidden ``toctree`` directives in the same page, or else the build
129+
# will break.
130+
#
131+
# Values: "true" (default) or "false"
132+
'globaltoc_includehidden': "true",
133+
134+
# HTML navbar class (Default: "navbar") to attach to <div> element.
135+
# For black navbar, do "navbar navbar-inverse"
136+
'navbar_class': "navbar navbar-inverse",
137+
138+
# Fix navigation bar to top of page?
139+
# Values: "true" (default) or "false"
140+
'navbar_fixed_top': "true",
141+
142+
# Location of link to source.
143+
# Options are "nav" (default), "footer" or anything else to exclude.
144+
'source_link_position': "nav",
145+
146+
# Bootswatch (http://bootswatch.com/) theme.
147+
#
148+
# Options are nothing (default) or the name of a valid theme
149+
# such as "cosmo" or "sandstone".
150+
#
151+
# The set of valid themes depend on the version of Bootstrap
152+
# that's used (the next config option).
153+
#
154+
# Currently, the supported themes are:
155+
# - Bootstrap 2: https://bootswatch.com/2
156+
# - Bootstrap 3: https://bootswatch.com/3
157+
'bootswatch_theme': "flatly",
158+
159+
# Choose Bootstrap version.
160+
# Values: "3" (default) or "2" (in quotes)
161+
'bootstrap_version': "3",
162+
}
96163
# Add any paths that contain custom static files (such as style sheets) here,
97164
# relative to this directory. They are copied after the builtin static files,
98165
# so a file named "default.css" will overwrite the builtin "default.css".

‎docs/core.rst

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
Core
2+
====
3+
4+
Description
5+
-----------
6+
7+
The core of the `skyr` library is a `skyr::url_record` that
8+
contains a URL parts, a `skyr::parse` function that parses an
9+
input string and creates a `skyr::url_record` and a
10+
`skyr::serialize` function that composes a URL string from an
11+
existing `skyr::url_record`.
12+
13+
Use these functions directly if your needs are simple. Use the
14+
`skyr::url` class for more complex operations, including
15+
Unicode encoding and decoding.
16+
17+
Headers
18+
-------
19+
20+
.. code-block:: c++
21+
22+
#include <skyr/core/url_record.hpp>
23+
#include <skyr/core/parse.hpp>
24+
#include <skyr/core/serialize.hpp>
25+
26+
27+
Example
28+
-------
29+
30+
.. code-block:: c++
31+
32+
#include <skyr/core/url_record.hpp>
33+
#include <skyr/core/parse.hpp>
34+
#include <skyr/core/serialize.hpp>
35+
#include <iostream>
36+
37+
int main() {
38+
auto url = skyr::url_parse("http://example.org/");
39+
std::cout << url << std::endl;
40+
std::cout << "Scheme: " << url.scheme << std::endl;
41+
std::cout << "Hostname: " == url.host.value());
42+
std::cout << "Pathname: ";
43+
for (const auto &path : url.path) {
44+
<< std::cout << "/" << path;
45+
}
46+
std::cout << std::endl;
47+
48+
std::cout << "Serializer: " << skyr::serialize(url) << std::endl;
49+
}
50+
51+
API
52+
---
53+
54+
`skyr::url_record` class
55+
^^^^^^^^^^^^^^^^^^^^^^^^
56+
57+
.. doxygenclass:: skyr::v1::url_record
58+
:members:
59+
60+
`skyr::url_record` functions
61+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
62+
63+
.. doxygenfunction:: skyr::swap(url_record&, url_record&)
64+
65+
.. doxygenfunction:: skyr::parse
66+
67+
.. doxygenfunction:: skyr::serialize

0 commit comments

Comments
 (0)